-----------------------------------------------------------------
|                                                               |
|       ////      /     /      /      ///   ///// ///////    /  |
|     /    /    / /    /      /       /   /         /      / /  |
|    /        /   /   /      /       /     /       /     /   /  |
|   /    /  ///////  /      /       /       /     /    ///////  |
|   ////  /       / ////// ////// /// /////      /   /       /  |
|                                                               |
|                    v e r s i o n   2 . 0 0                    |
|                                                               |
|                   (C) 28-Feb-1992 BoLuSoft                    |
|                                                               |
-----------------------------------------------------------------



   Notice
   ------
   This  software can run only in conjuction with  BinkleyTerm-ST 
and ACS.  If you do not use,  do not intend to use or even do not 
know these software packages,  then Callista brings you no use. I 
expect  that  you  are familiar with both  these  programmes  and 
understad basics of Fido-technology-networks as well.



   What you should have
   --------------------
   Distribution archive should contain following files.  If  some 
of them are missing,  please obtain another copy of  distribution 
archive or contact me personally.

   CLST102B.ZIP:
    - CLST_ST.TTP  ... ST version of Callista
    - CLST_TT.TTP  ... TT version of Callista
    - CALLISTA.TXT ... This document
    - HISTORY.TXT  ... History of changes



   ST and TT versions
   ------------------
   Because  M68020 and higher CPUs  have many changes  that  make 
compilation  more  efficient,  I included  specific  version  for 
Atari TT,  which employs M68030 CPU.  I say TT-specific  version, 
but in fact it only requires any TOS computer with M68020 CPU  or 
higher  and M68881/M68882 FPU.  So if you have some  of  upgrade-
boards you may also use TT-version.



   Callista? What is it for?
   -------------------------
   This  is  the most basical question  you may  have  about  any 
software product, so sorry I let you waiting for the answer.
   Callista can do several things. The first and most general one 
is area-file-insertion.  In the other words it can take any  text 
file  and  insert  it as new message into  chosen  area  of  your 
messagebase.  This  can be done manually,  from command  line  or 
automatically  once in given period you set up.  This feature  is 
primarily  meant for regular inserting rules of  conferences.  If 
you're  a moderator of one,  you can set up Callista,  and  don't 
care any more.  The second main ability is creating area-reports. 
Area-report is list of all area participants sorted by number  of 
messages  written.  Such  report can be directed into a  file  or 
inserted  to area it was made from.  Reports can be  created  and 
inserted fully automatically once a defined time.



   What files it needs to run
   --------------------------
* BinkleyTerm-ST: BINKLEY.CFG
Keywords  Address and Sysop must be present;  StatusLog  is  only 
optional for Callista.

* ACS:            AREAS.BBS
Needed  to know where you have stored your messagebase  and  also 
names of your areas.

* ACS:            ACS.CFG
Only EchoList entry is relevant for Callista.  When no such entry 
exists, there will be no EchoList written.

* Callista:       CALLISTA.CFG
Here is stored information for automatic mode.  This file is user 
created,  Callista won't change it.  Detailed info later in  this 
doc.

* Callista:       CALLISTA.INF
This file is created and maintained by Callista itself.  It holds 
information   for automatic mode.  You should never  change  this 
file. Detailed info later.

   Note: All these files must be present in CURRENT directory!



   System requirements
   -------------------
#> TOS versions:  should run on all versions.  Tested with german 
TOS 3.06.
#> Memory: You should have about 200-300KB of free space (depends 
on size of processed files.
#> Storage requirements:  no special requirements. Only space for 
output files is needed.


   So, here we had some declarations, main part of doc follows...



   1. Use of Callista
   ------------------
   Callista recognizes two main modes  of operation:  manual  and 
automatic.  Manual  mode  is active every time you  run  it  with 
parameters.  In  this  mode  Callista will  not  perform  regular 
insertion  of rules/reports even it is time to do  so.  Automatic 
mode  is active whenever is Callista run without any  parameters. 
In  this mode it will check configuration and INF file  and  when 
needed it will make file or reports insertions.



   1.1  Manual mode
   ----------------


   1.1.1  Syntax
   -------------

Syntax of command line arguments:

CLST [-ir][-ifFILE.TXT][-oREPORT.TXT][-aAREA][-hAREA.HDR]
     [-re][-ru]

   There must be at least one space between parameters.  '/'  can 
be used instead '-'. All paremeter are position-independet. Whole 
command line is case-insesitive.



   1.1.2  Parameters overview
   --------------------------

-ir ... insert report
-if ... insert file
-o  ... specifies destination for report generations
-a  ... specifies area
-h  ... specifies hudson messagebase HDR/MSG file
-re ... reset report counter
-ru ... reset rules counter



   1.1.3  Parameters - detailed
   ----------------------------

>>> -a  specify area <<<

   This parameter specifies an area  to which will be  bound  all 
following  commands (if any).  This must be real,  existing  name 
otherwise an error occur.

>>> -h  specify HDR/MSG file <<<

   This  parameter  can be  in some cases  used  instead   of  -a 
switch.  It  determines directly file where area is  stored.  You 
don't need to add any extension,  but it won't mind if you'll  do 
it.  Note,  that this parameter overrides -a parameter. This mean 
when you eg.  enter -aATARIST -hSYSOP,  then area stored in files 
SYSOP.HDR and SYSOP.MSG will be processed instead of ATARIST.  Do 
not  forget  to specify path if message files  are  in  directory 
different from current one.

>>> -o  specify output file for report <<<

   This parameter tells Callista,  that report has to be  written 
into given file instead of the specified area.  This is good  for 
generating info for your BBS's bulletins and top writers list.

>>> -ir  insert report <<<

   Creates  a  report  (a list of participants  sorted  by  their 
activity) from area defined by -a or -h parameter.  If there's -o 
switch  then  it  is written into given  file,  otherwise  it  is 
inserted into area itself.

>>> -if  insert files <<<

   This commands makes Callista insert given text file into  area 
specified in -a or -h parameter.  Text is plain ASCII  file.  The 
first  line of text is supposed to be  subject!  of  message.  It 
cannot be,  of course, longer than 76 characters. Whole text file 
is limited to 32 KB size.

>>> -re  reset report counter <<<

    Use of this command is somehow connected with automatic  mode 
which  is discussed later.  But in brief:  In auto-mode  Callista 
remembers  for  each entry in config the last  date  it  inserted 
report/rules into messagebase.  Via -re these counters,  but  not 
all,  only for report,  are set to today's date. When you specify 
area with -a,  then only report counter for given area is  reset, 
otherwise all.

>>> -ru  reset rules counter <<<

   This is like -re but for rules counter.



   1.1.4 Examples
   --------------

   CLST -aLOCAL -ir -oREP_001.TXT

Creates  in current directory file REP_001.TXT with  report  from 
area LOCAL.

   CLST -aSYSOP.42 -ir

Creates report from area sysop and inserts it into the same  area 
(guess, where's report? - solution: in area SYSOP )

   CLST -hF:\FIDO\MSGS\USER_420 -ir

Here  a  report  is  created and inserted  into  area  stored  in 
USER_420.HDR and USER_420.MSG.

   CLST -if68000.RUL -a68000.42

File 68000.RUL is inserted into area 68000.42.

   CLST -re

Resets all report counters for all areas.

   CLST -re -ru.

Resets all counters for all areas.

   CLST -re -aFIDOCON

Resets report counter for area FIDOCON.



   1.2  Automatic mode
   -------------------
   In  automatic  mode all actions are performed  accordingly  to 
config file.  So that automatic mode REQUIRES this file to exist. 
Auto-mode  makes  sense only when Callista  is  regulary  invoked 
(the  best is once a day) in some way - you can use batches  with 
Binkley's EVT file to do so.



   1.2.1  Configuration file
   -------------------------
   Configuration file is called CALLISTA.CFG.  It is plain  ASCII 
file and has following format:

---[ CALLISTA.CFG ]----------------------------------------------
Report <AREA1><days,num>
Rules  <AREA2><days><filename>
...
-----------------------------------------------------------------

   The first word may be "Report" or "Rules" and  determines,  if 
the  entry  is  about launching reports or rules  (or  any  other 
files).
   The  second  word is area name.  Here cannot be  filenames  of 
hudson messagebase! 
   Days mean, how often shall be report/rules inserted.
   In case of report,  num determines how many entries can report 
have (stupid formulation, look on examples below).
   In case of rules filename is text file which is to be regulary 
inserted into area.

   Note:  maximal number of entries in configuration file can  be 
100!



   1.2.2  Example of configuration file
   ------------------------------------

---[ example ]---------------------------------------------------
Report 68000.42 14,3
Rules  68000.42 31 F:\FIDO\RULES\68000.TXT
Rules  ATARIST  20 F:\FIDO\RULES\ATARIST.TXT
-----------------------------------------------------------------

   This config will make Callista do following:

- insert report containing three most active users into  68000.42 
  area every two weeks (=14 days)
- insert file 68000.TXT into area 68000.42 every month (=31 days)
- insert file ATARIST.TXT into area ATARIST every 20 days



   1.2.3  Running in auto mode
   ---------------------------
   On first run,  when no CALLISTA.INF file exist,  it is created 
new one.  INF file contains (in packed form) date of last  event, 
when something happened (INF was created,  or action was  carried 
out).  Upon each run of Callista all entries are checked.  If  in 
some  entry  the  date is older than specified  number  of  days, 
action  is  performed.  Then in INF file the date is  changed  to 
today's one,  and INF file is updated.  If you look at INF  file, 
you notice that it is simple ASCII file similar to CFG.  The last 
number on line is only for your information:  it shows,  how many 
days passed from last event.
   You should never change INF file,  otherwise Callista may  not 
operate correctly. You can only delete file. This causes Callista 
to generate new one with all dates set to today.  Using -re and -
ru  commands  from command line you can reset (this mean  set  to 
today)  all event-dates.  In our example:  imagine,  the time  of 
launching  rules in 68000.42 is drawing nearer,  but you want  to 
suppress it for now.  So you run Callista with "-a68000.42  -ru", 
and next rules will be inserted after month from today.



   1.3  Other features
   -------------------
# When inserting into any area,  Callista will write the areaname   
  into file specified in ACS.CFG by keyword EchoList.  This isn't   
  performed when no EchoList is given.  This file is used by  ACS 
  to determine which areas have changed.
# Callista  will append short info about its run  into  Binkley's 
  logfile (if defined).



   2.1  Legal
   ----------
   This programme is freeware. It means that you can spread it as 
long  as the programme and distribution archive stays  unchanged. 
If  you want to know about it's development,  please register  by 
sending a netmail.



   3.  Author's address and last notes
   -----------------------------------
   I  will  welcome  any  bug  reports,  advices,  questions  and 
interesting ideas. Please always feel free to contact me.
   For  English  speaking people  I have  to  appologize  for  my 
English - it really is far from being ideal.

   Please note,  that I am at home only on weekend,  so there may 
be slight delay before I answer your potential request.

   I do not intend to keep developing this software unless  there 
will be demand to do so.  I can't take a full use of my programme 
because I'm only a simple node in FidoNet. I wrote only because I 
learnt C language - it serverd very well.  Any other  development 
without users of my programme wouldn't make much sense but  would 
be wasting my sparetime.

   I  tested this programme relatively long time before giving it 
away.  You can see it in history file: the time between the first 
beta  version and release version it was running on my  node  and 
was runnig well.  So I hope there'll be no more fatal  errors.  I 
wanted  to get someone to test it in real echomail  traffic,  but 
here's too few Atari-based nodes in Bohemia.


   Borek Lupomesky
   Marvanova 4
   Usti nad Labem, zip code 40012
   Czech Republic
   tel/TAD: +42-47-45816
   
   E-mail: 2:423/71@fidonet.org

Czech or Slovak users can reach me at 68000.42 echo.


---------------------------- THE END ----------------------------
