OS/2 Shareware BBS: OtherApp/OtherApp.zip/ellie03.zip/ReadMeV3.txt

Text File | 1999-07-30 | 20KB | 435 lines

Ellie03.readme.  Draft 1.  [for version r2a]
--------------------------

Ellie is a multi-threaded application to monitor a running setihome.exe process
on OS/2.

Ellie has been designed with the multitasking abilities of OS/2 in mind.  This
means that she is not only multi-threaded but unobtrusive, elegant and quite
happy sitting neatly somewhere on your screen while you go about your work on
your computer.

So, with OS/2, setihome.exe and Ellie, you can crunch the WU while working with
Ellie only taking up as much or as little of the screen as you want.  The
program revolves around the 'Elliebar', an unobtrusive bar graph that you can
place anywhere on your desktop.
______________________________________________________________________________

Installation:

Unzip the ellie(version ID).zip to a directory of your choice.
DO NOT INSTALL into the same directory as your setihome client.

If you are upgrading over an old version you may install into
the same directory ensuring that all files are replaced by the unzip
program.  Your ELLIE.INI file will be left intact and will be automatically
upgraded as you use the program.

[Step 1] Run INSTALL.CMD.

Follow the instructions presented to you.

The script will install a folder on your Desktop containing the Ellie program
object, a shadow of a folder containing WAV files for use with certain alarm
features of Ellie (especially for future versions), a shadow of this readme file
and a shadow of the seti.exe client document.

[Step 2] Please ensure to close your setihome.exe client session if it is
running (unless you are running the client through a previous version of Ellie.)

Double-click on the Ellie object in the Ellie folder.

In the lower left of you screen you will find Ellie, quietly awaiting further
setup.  Right-click on the graph and select 'Settings' from the pop-up menu.

Make you way to the 'Client Control' tab.  At the top of the page is a grouping
called 'Client Location'.  We need to inform Ellie where your setihome.exe
client resides.  So,

1. click on the button '..'  on the righthand side of the entry field and, from
   the file selector make your way to where setihome.exe is on your hard disk.

2. Select any file in the directory..  it doesn't matter which one as Ellie
   will discard any filename you select and use only the drive and path
   information.

3. Press Save.

You may notice an LED on the EllieBar illuminate bright red.  This is because
Ellie may have suddenly found data she can use and finds interesting (before you
told her where to find seti data she was idly scanning nowehere in particular!).
So, don't worry.  More information on this LED later.

You should hear a beep or two as Ellie reinitializes the threads to point at the
directory you selected.

The items below this section, namely SETIHOME Client Control, should now be
enabled.

If you want Ellie to be able to control the setihome.exe sessions,
choose 'Create SETI Client Object'.  This will create a WPS object in your
Ellie folder and copy the SETI.EXE in Ellie's directory file to your seti@home
directory.  (This file does not intefere with the setihome.exe client program
but, as the object that gets created in your Ellie folder has an Object ID,
it can be launched via the Workplace Shell.)

If this process was successful, further options should avail themselves to
you which take affect immediately.

You can choose to start and stop the s@h client via the Workplace Shell and
have Ellie automatically start and/or stop it whenever she herself is started
or stopped.

You can get straight to this notebook page by right-clicking on the leftmost
LED and selecting 'Setup Client Control' from the popup menu.

Ellie has now been setup.
______________________________________________________________________________

Usage:

The first time you run Ellie, the bargraph will be in the lower corner.  I
shall refer to this window as the EllieBar from now on.

The Elliebar is the 'console' or 'main menu'.  It occupies little room and so
allows some feedback for the user despite whatever they're doing.  If you move
the Elliebar or change some of its settings, they will be remembered between
sessions.


There are two LEDs beside the graph.

The leftmost one signifies whether Ellie has control of the setihome client
session.  Right-clicking on the LED will bring up a popup as you would expect
that allows you to start and stop the client or go straight to relevant pages
in the Settings notebook.  Remember, at this juncture, if you manually close
down the client, Ellie will not know so the LED may still glow green (or
conversly, not at all).  Future versions of Ellie will be notified by the
client but it depends on other matters right now.  Right now, it informs you
if Ellie has been configured to control the client or not and, if so, whether
Ellie has launched a client (green) or closed it (off).

The rightmost LED is 'live' that is, under the control of a thread scanning
data that the client writes to disk.  If the LED is dark (ie off) it means that
no data has been found in the current WU being processed.  If it is yellow,
that means that the WU does contain 'interesting data'.  You may notice that an
alarm may sound and the LED glows red.  This means that more interesting data
has been found since the last poll.  The LED will eventually revert to yellow
in this case.  Double-clicking on the LED will interrupt the thread for it to
install the correct LED.

(This 'Interesting Data' (or rather Spikes and Gaussians) is subject to various
design and data massaging at this stage of the game.  Expect to see more
functionality in (near) future releases of Ellie.)

Right click on the Elliebar or around it and up will come another popup menu
offering further options:-

POPUP MENU:

The Settings notebook:

WU Alarms:
---------
This notebook page allows you to allocate alarms to sound at a defined
percentage achieved value (say, at 50%) and/or at a defined 'minutes
to go' value by using the slider object or spin buttons to set up values
accordingly.  The types of alarm include (and are not exclusive of each
other) a flashing clock, a flashing bargraph and a beep.  Furthermore,
the length of times these alarms sound for can be chosen (so, for
example, you could have the clock flash for one minute with the bargraph
flashing for an extra minute while the computer beeps all the while and
for another ten minutes thereafter).  One can also elect to have a logfile
generated by ticking the respective tick box and entering a filename in
the entry field supplied.  The alarms take affect on closing the
notebook or pressing the Apply/Reset button for them to reinitialize
immediately.

Pressing Alt-Space on any of Ellie's windows with silence a sounding alarm
as will double-clicking the clock icon on the Progress Window or using
the popup menu presented from right-clicking on it.  For windows with
a system menu, you will have to press Alt-Space quicly in succession otherwise
OS/2 will offer you its standard System Window menu list.

Please Note:  Ellie gathers its information from files written periodically
to disk by the setihome.exe client.  While I have witnessed the odd
100% complete, usually all data updates seem to stop at the 97% mark.  This
seems to be a bug with the client in that it stops writing to disk at about
this period for reasons of its own despite it continuing to process the WU.
As a result, alarms to sound at or near the end of a WU process will sometimes
never sound.  As far as I am aware, this is not a limitation of Ellie.. she
just hasn't been given the relevant information by the client!

Polltimes:
----------
Changing the value for the WU Progress slider will change how quickly Ellie
syncs with setihome.exe.  The poll time is reflected in a button which you
must click to set the polltime you may have selected.  Changes take
affect immediately.

You can also choose how often Ellie looks to see if setihome has found any
'Interesting Data'.  Similarly, there is a button to have changes take affect
immediately.

Beside the 'ID' poll setup is the alarm setup for this thread.  You can disable
all alarm noises, opt for a beeping from the PC's speaker or use a WAV.  If
there is no WAV in the container, double- clicking there will automatically
open the EllieWavs folder.  Drag a WAV file from there (or anywhere else, of
course).  Once a WAV is in place, double-clicking it will play it through the
OS/2's multimedia subsystem.


Client Session:
---------------

This is where you can setup the client's priority and how it reacts after the
WU is finished with.

Pressing the Advanced button brings a window up for you to specify what batch
files/programs/scripts are run before (PreProcess) and after (PostProcess) each
client session controlled by Ellie.  You may also enter the name of a logfile
where detailed information is written.

The 'mini-VIO' tickbox controls the size of the client session.  Unticking it
leaves the VIO screen at default, ticking it reduces it to 40x10 (my
preference).  I have a few ideas (especially for 4OS2 users which seticlient
detects) but if you would prefer a different size etc, let me know.

You may instruct the client to run minimized.

If you opt to run the client as a seamless session (setihome v1.3 and above
only), you can see the output of the program by selecting
'Open.. client session' from the Elliebar popup menu (which can also be
accessed by double-clicking on the clock).  This window is sizeable and will
remember dropped colours and fonts.  A seamless session will be launched and
terminated along with Ellie.


Changing any of these settings requires you to select 'Apply'.  This will
update the Seticlient object with new paramters for subsequent client sessions.
I have plans to automatically recycle the client but for now, if you want
changes to take effect, click on the Client Control tab, stop the client and
restart it.

'Version information' displays the version information of the client.


Misc:

If you have SysBar/2 installed on your system, you can configure a Pipe
Listener which Ellie will output to.

You can also create an URL to go straight to your stats page at seti@home.


Titlebar Display:
-----------------
Will display a submenu enabling you to choose what data is displayed in the
title bar of the progress window which updates in realtime.  This information
is also reflected in the Window List or the Minimized Windows folder.

If you select Name, the titlebar simply displays 'Ellie'.  This is to
accomodate users with virtual desktops that rely on information in the
Windows List not changing.

You can choose to display:

o The current progress percentage of the current WU,
o The estimated time it will take to complete the current WU at current system
  load,
o How long it will be before the current WU is completed at current system load,
o How much time the CPU has spent crunching the current WU.
o The percentage per hour rating for your machine and WU.

Show Clock:
-----------
This brings up an analogue clock showing today's time.  This menu item changes
to Hide Clock if the clock is showing.  Ellie will remember the fact you had a
clock showing or not when you close her down.  You can also double-click the
clock to quickly (re)display the Progress Window.

Refresh:
-------
This interrupts the WU status thread and updates information here on the
titlebar and elsewhere in the program.  Remember, it can sometime take the
setihome.exe client up to 60 seconds before it updates its status for Ellie so
if you ask Ellie to refresh her data and the s@h client hasn't written anything
new to disk, Refresh will have no affect.

Pressing F5 here (and elsewhere in the program) will cause a refresh too.

Open..:  (This menu can also be displayed by double-clicking on the clock).
-------
You can find lost windows by surfacing them from this menu ( Ellie will remember
where you position her windows and if they were open you close her down).

A submenu will display giving you the choice to display various information
regarding the current WU process.

Progress Information Window:

This window displays time orientated information for the WU being
processed.

Right-clicking on the clock icon in the bottom left of this window will present
a menu with the following options:-

    - Calibrate - Use SETI timings
                - Use Ellie timings.

All timings are calculated directly from the data written out by the client.
However, switching over to Ellie's timing mean actual times are compared through
the course of many polls and thus present a more indicative representation of
how system workload affects the time it takes to process a WU in its entirety.

On a completely idle machine the SETI timings and the Ellie timings should
settle down be practically identical.  However, as a machine is used you should
see the Ellie timings start to represent the fact that clock cycles have been
taken away from the client.  Let's find out if the theory holds :) .

Status Window:

This is really a leftover from v01.  Expect to see more 'sweetened' data in
subsequent releases of Ellie.  Currently, it simply shows a view of the state.txt
file as being updated by the s@h client.

Percentage Per Hour graph:

This window will display an updating graph of the percentage per hour progress
of the cureent WU process.  Currently, the graph has two scales: 100% where the
height of the graph represents 100%; and 10% where the height of the graph is
10% thereby 'zooming' in on the plot so as to allow a more detailed view of
fluctuations.  I shall incorprate more 'zoom' scales if this proves popular
and/or useful.

By selecting 'Show Progress', another graphical representation of the percentage
done value is superimposed on the graph in a different colour.

The text values in the top left of the graph are of the same colour as the plots
themselves.

Double-clicking the graph will bring up a small window to allow you to choose
what colours you want the graph and its lines to be.  Unfortunately, as of now
you will have to close the window and re-open it for the colours (mainly the
background colour) to take effect.  I hope to address this soon.

Client Session:

This window will display the output of a seamless client session.  Ellie
will remember where you place it and what colours and fonts you drop into it.
Right-clicking will bring up a popup menu allowing you to save the contents of
the window to a file, clear the contents and stop and start the client.

Closing this window does not affect the running of the client.

Skymap:

This will display a map of the night's sky along with a flashing yellow cross icon
representing the origination of the data in your current WU.

Right-clicking on the map will present a menu to choose different sizes (from quite
small to rather large) of skymaps and a (basic as of now) WU information window.

If the titlebar of the Skymap somehow finds its way out of your reach outside the
boundaries of the monitor, there is an option to centre the window on your desktop.

Expect some seriously fun things to occur with this map in (near) future releases
of Ellie...  !!:)

You can also gain access to Ellie's desktop folder and her URL folder.


About:
------
Displays version information for this program.  Double-clicking the SETI logo
will close this window as will pressing ESCape (the Escape key will close
almost all of Ellie's windows).

______________________________________________________________________________

Author's Note: This is Version 0.03 of Ellie.  There are plenty of other
features awaiting activation.  The important issue for me at this moment in
time has been getting the thread engine stable and the design personality of
the program in place.  If this candidate appears stable, I can add further
features safe in the knowledge that the core functionality of the program is
solid.  It is so easy to chase the 'eye candy' while ignoring the actual
internal design of a program.

SETI.EXE This is a 'wrapper' program I have written to provide mutex
semaphoring of the actual client and so prevent monitor apps launching
multiple instances of the client.  It also allows logging of sessions to a
definable logfile and the running of scripts/programs/batch files before and
after a client session.

By using seti.exe, 3rd party apps can detect whether a
setihome.exe client is already running.  If you prefer to launch
the client by means other than various monitor apps, please run seti.exe
without any parameters for a usage guide or see the Seti.txt file in Ellie's
folder.

If you want to incorporate seti.exe into a application/script/etc you
are writing, please contact me.

I have further plans for Seti but would welcome involvement from others.

Currently supported apps:

Ellie v02 or higher
CQ verson 1.3 or higher.

______________________________________________________________________________

NOTE:  There is an inherent problem with having any application other than the
setihome.exe client opening a file that it expects only to be opened by itself.
As the client and various monitors are running in 'realtime', if one
application is reading a file while, =at the same precise time=, another
program is writing to the same file, a conflict can arise.  Ellie will simply
wait and try again for a few times, however setihome.exe will die gracefully.

SETIHOME.EXE v1.2 was not designed with 3rd-party realtime monitors in mind
therefore if it attempts to write an important file while finding it in use by
another application it will 'fall over'.  This is not a reflection on either
the people who wrote the setihome.exe client or the authors of any 3rd party
monitor application.  It is simply because the situation was not anticipated at
the design stage of the setihome.exe client and precautions were not written
into the setihome.exe code.

There are ways around this.  If setihome would wait for a while and try a few
times without falling over when it finds its files 'owned' by someone else it
would help enormously.  But there is a failsafe method.  OS/2 itself offers a
developer very fast system semaphores to protect against exactly this kind of
situation.  With semaphores, it is OS/2 who decides when data can be
read/written.  It is hoped that the next version of the setihome client will
support 32bit system semaphores.  This will practically guarantee one hundred
percent stability as OS/2 would be allocating access with microsecond accuracy.

The other method open at this stage is for any third party app be
extremely swift about opening/reading/closing data from files that, basically,
do not 'belong' to it.  Ellie has been designed to be as fast as possible in
obtaining data from the setihome client's files.  It currently takes a hundred
times longer to =display= data than to read it.

For systems with Fixpack 6 or higher applied there is another method.  I shall
be integrating this into Ellie 03.
______________________________________________________________________________

I hope the program works for you.  KEEP ME INFORMED!!!  If it breaks, looks
nothing like my screenshots I need to know!!  If you can think of a feature,
let me know!!

Clive (et or [e-mail] )
______________________________________________________________________________
Ellie ?  The program name comes from the book Contact by the late Carl Sagan.
A film was made of the book but, as you would expect from Hollywood, many key
points from the books were ommited.  If you're running SETI@Home, I urge you to
read the book (and =maybe= see the film..  the opening minute is tremendous).
______________________________________________________________________________

Disclaimer:  the program is only guaranteed to take up disk space (I'm a Brit
dealing with Americans so you cannot blame me!!  :-) ).


DEREG.CMD will unregister Ellie's OS2.ini file references and objects from the
Desktop.