Anleitung zu Stber v1.5 vom 20.12.98

-----------------
1. Sinn und Zweck
-----------------

Es gibt diverse Programme, die es erlauben, Filelisten von verschiedenen 
Musen zu verwalten. Ein dabei auftretendes Problem ist die Aktualisierung 
der Listen. Dazu gibt es verschiedene Mglichkeiten. Die erste und teuerste 
Mglichkeit ist, von den bentigten Musen in regelmigen Abstnden neue 
Filelisten zu saugen. Die zweite Mglichkeit ist, die Nachrichten in 
Maus.Info.Programme oder anderen Mausgruppen auf Filelisten zu durchsuchen, 
diese abzuspeichern, im Filelistenverwaltungsprogramm die entsprechende 
Liste zu laden und mit den neuen Daten zu aktualisieren. Das ist sehr 
zeitaufwendig und auerdem eine Routineaufgabe, die man eigentlich dem 
Computer berlassen knnte. Damit kommen wir zur dritten und elegantesten 
Lsung: Ein Programm durchstbert selbststndig das Outfile nach Filelisten 
und speichert diese in eine Stapeldatei ab. Das Filelistenverwaltungspro-
gramm liest diese Datei dann ein und aktualisiert die Listen automatisch. 
Genau dieses macht Stber nun in Verbindung mit Filelist. Hierbei knnen 
nicht vorhandene Datenbanken bei Bedarf automatisch erzeugt werden.

---------
2. Status
---------

Stber ist Freeware. Das bedeutet, Stber darf frei kopiert und weiter-
gegeben werden, solange dies unentgeltlich geschieht. Verbreitung auf 
'Servicedatentrgern', gleichgltig ob Diskette, CD oder sonst etwas, 
ist nur nach vorheriger Genehmigung gestattet. Dies gilt ebenfalls fr 
sogenannte PD-Serien, bei denen der Diskettenpreis 2.50DM/Disk bersteigt.

---------
3. Aufruf
---------

Stber ist ein TTP-Programm, d.h. es hat keine GEM-Oberflche, sondern 
erwartet seine Parameter in einer Kommandozeile. Am sinnvollsten ist der 
Einsatz als Outfile-Filter in CAT. Dazu starten Sie CAT und whlen den 
Menpunkt Optionen|I/O-Filter an. In der sich ffnenden Dialogbox whlen 
Sie einen freien Filterslot aus. Geben sie in der nchsten Zeile als Name 
'Stber' ein und kreuzen Sie 'aktiv' an. Nach einem Klick auf den (noch 
leeren) Programmnamen suchen Sie mit dem Fileselektor STOEBER.TTP. Whlen 
Sie es an und drcken Sie OK. Der Schalter 'Errorbreak' kann ausgeschaltet 
bleiben, ein Fehler im Stber-Lauf hat fr die weitere Outfile-Bearbeitung 
keine Auswirkungen. Unter 'Wofr' mu 'fr In-/Outfile' stehen, zustzlich 
mu der Schalter 'fr Outfile' angekreuzt sein. Die Kommandozeile fr das 
Infile lassen Sie leer, in die fr das Outfile tragen sie die Parameter fr 
Stber ein.

Die allgemeine Syntax lautet:

stoeber -i<INF-Datei> [-o<Outfile>] [-v] [-t]

In der Kommadozeile im Dialog braucht der Programmname nicht noch einmal 
angegeben zu werden. Also geht es gleich mit den Parametern los:

-i<INF-Datei>

   Dieser Parameter spezifiziert eine INF-Textdatei, die die Konfiguration 
   fr Stber enthlt. Der Parameter wird immer bentigt, der Pfad wird 
   ohne Leerzeichen direkt hinter -i geschrieben.

[-o<Outfile>]

   Hiermit wird das zu bearbeitende Outfile angegeben. Der Parameter ist 
   optional, weil der Pfad zum Outfile auch in der oben angegebenen INF-
   Datei stehen kann. Allerdings kann man mittels Parameter -o die Angabe 
   aus der INF-Datei berlagern, ohne die Textdatei ndern zu mssen.

[-v]

   Stber erzeugt eine Logdatei, in der der Programmlauf protokolliert 
   wird. Mit dem Schalter -v wird zustzlich eine ausfhrliche Liste der 
   Konfiguration in die Logdatei ausgegeben. Da alle Ausgaben grundstzlich 
   an die Datei angehngt werden, sollte dieser Schalter normalerweise aus 
   bleiben, sonst wchst die Gre der Datei unntig schnell an.

[-t]

   Dieser Parameter schaltet den Testmodus ein. Ist er angegeben, so wird 
   die INF-Datei ausgewertet und berprft, aber kein Outfile bearbeitet. 
   In der Logdatei steht anschlieend, ob alles in Ordnung war.

Im CAT-Dialog geben Sie als Kommandozeile am zweckmigsten dies an:

-iE:\CAT\STOEBER.INF -o$I$O

Als Pfad zur INF-Datei geben Sie natrlich den auf Ihrem Rechner richtigen 
an. Das $I$O wird von Cat automatisch durch den Pfad und Namen des Outfiles 
ersetzt.

--------------------------------------
4. Die Konfigurationsdatei (INF-Datei)
--------------------------------------

Die INF-Datei ist eine reine Textdatei, die Sie mit jedem Editor anlegen 
und bearbeiten knnen, z.B. auch mit CAT. Aufgrund der komplexen Konfigura-
tionsmglichkeiten ist diese Beschreibung etwas umfangreich geworden, dafr 
sollte Sie immerhin leicht verstndlich sein. :-)

In der beiliegenden Datei BEISPIEL.INF sind schon einige Mglichkeiten 
der Konfiguration enthalten, hier wird es nun genauer. Das einfachste 
ist wohl, da Sie die BEISPIEL.INF einmal auf den Namen STOEBER.INF 
duplizieren und die neue Datei an Ihre Bedrfnisse anpassen.

-----------------------------
4.1 Die Inhalte der INF-Datei
-----------------------------

Die ersten drei Angaben #Logfile, #Outfile und #Gesamtfile sind lediglich 
Pfadangaben zu den Dateien, mit denen Stber arbeitet.

Ausgaben in das Logfile werden dort grundstzlich angehngt. Im Normalfall 
kommen da pro Lauf aber nur gut 80 Bytes zusammen.

Als Outfile sollten Sie den Pfad angeben, an dem das Maus-Outfile 
normalerweise abgelegt wird. Wird Stber beim Start in der Kommandozeile 
ber den Parameter -o mit einem Outfile-Namen versorgt, so wird die Angabe 
in der INF-Datei ignoriert.

Die hinter #Gesamtfile konfigurierte Ausgabe-Stapeldatei ist die, die 
spter von Filelist gelesen wird. Auch hier hngt Stber neue Daten 
grundstzlich an, so da nichts verloren geht, wenn Filelist den Stapel 
mal ein paar Tage (oder auch Wochen ...) nicht abgearbeitet hat.

Hinter #Gruppen werden alle Gruppen angegeben, die Stber nach Filelisten 
und neuen Uploads durchsuchen soll. Um auch die PMs durchsuchen zu 
lassen, geben Sie die Gruppe Persnliche an. Das ist z.B. sinnvoll, wenn 
Sie sich von James, dem Butler der Maus, Filelisten per PM schicken lassen.

Das letzte und interessanteste Schlsselwort der Konfiguration lautet 
#Dateien. Hier kann auf verschiedene Weise angegeben werden, was Stber 
mit den gefundenen Filelisten-Eintrgen anfangen soll, und wahlweise 
auch, wo Filelist die Daten spter speichern soll.

-------------------------------------
4.2 Aufbau der Zeilen hinter #Dateien
-------------------------------------

Jede Zeile mu der folgenden Form entsprechen:

#M<Maus>, #T<Programmteil>, #S<Systeme>, #D<Datenbank>

Die ersten drei Angaben #M, #T und #S sind die Kriterien, mit denen 
bestimmte Filelisten-Eintrge ausgewhlt werden. Hinter #D steht, was 
mit den Eintrgen passieren soll.

Dabei werden fr jeden einzelnen Filelisten-Eintrag alle Zeilen von 
oben nach unten geprft, und falls die Kriterien dabei auf den Eintrag 
zutreffen, die Angabe hinter #D beachtet. Dann werden fr diesen 
Eintrag keine weiteren Konfigurationszeilen geprft. Wurden alle 
Zeilen geprft, aber kein Kriterium traf zu, so wird der Eintrag in 
die Stapeldatei bernommen.

Die mglichen Angaben bei den Kriterien anhand von Beispielen:

#M *     alle Muse
#M BL    Maus BL
#M `BL   alle Muse auer Maus BL

#T *             alle Programmteile, PTs und GPTs
#T OEPT          nur PTs (ffentliche Programmteile)
#T `OEPT         nur GPTs (Gruppenprogrammteile)
#T MausTausch    nur GPT MausTausch
#T `MausTausch   alle Programmteile, auer GPT MausTausch
#T FTN.*         alle Gruppenprogrammteile, deren Name mit FTN. anfngt

#S *          alle Systeme
#S ST TOS     nur System ST TOS
#S `ST TOS    alle Systeme auer ST TOS

Bei Gruppenprogrammteilnamen hinter #T sind auch die Wildcards * und ? 
erlaubt. Die Schreibweise der Namen ist beliebig im Rahmen der Toleranz, 
die auch die Maus an der Stelle erlaubt. D.h., zwischen Gro- und 
Kleinschreibung wird nicht unterschieden, Umlaute knnen direkt oder 
in ihrer expandierten Form angegeben sein ( = ae, usw.) und alle 
Sonderzeichen werden intern gleich behandelt. Die Gruppennamen 
"Maus.Bcher" und "MAUS-BUECHER" werden also als identisch erkannt.

Als Kommando, was mit den gewhlten Filelisten-Eintrgen passieren 
soll, sind hinter #D zulssig:

#D -                der Eintrag wird nicht in die Stapeldatei bernommen

Bei allen anderen Angaben wird der Eintrag in die Stapeldatei 
bernommen, Sie knnen aber noch genauer bestimmen, wie:

#D +                Die richtige Datenbank whlt Filelist automatisch.
                    Das funktioniert immer problemlos, auer es gibt 
                    mehr als eine "richtige" Datenbankdatei (z.B. zwei 
                    verschiedene FLS-Dateien mit dem PT der Maus B3).

#D name.fls         Filelist soll den Eintrag explizit in die angegebene 
                    Datenbankdatei importieren. Die Datei mu sich dabei 
                    im konfigurierten Basispfad der Filelisten befinden.

#D ordner\name.fls  Wie oben, nur liegt die Datenbankdatei in einem 
                    Unterordner, der sich im Basispfad befinden mu.

#D ordner\          Diese Angabe wirkt genau wie #D+, allerdings wird eine 
                    bisher noch nicht vorhandene Datenbank nicht im 
                    Basispfad, sondern im angegebenen Ordner neu angelegt.

---------------------------------
4.3 Besonderheiten bei Lschungen
---------------------------------

In den Nachrichten z.B. der Gruppe Maus.Info.Programme stehen auch Angaben 
ber Lschungen von Dateien. Diese werden genau wie neue Uploads ber die 
Stapeldatei an die Filelisten weitergegeben.

Die Angaben ber Lschungen mssen normalerweise ohne Angabe des Betriebs-
systems auskommen. Dies hat Folgen, wenn Sie einen Programmteil nach 
Betriebssystem gesplittet in mehreren FLS-Dateien aufheben. Die Lschungen 
knnen zwar nach Maus und Programmteil unterschieden werden, nicht aber 
nach Betriebssystem. Deshalb sollten Sie sich in diesem Sonderfall ent-
scheiden, welche der in Frage kommenden FLS-Dateien die Lschinformation 
erhalten soll.

Zu diesem Zweck knnen Sie eine besondere Zeile einfgen, bei der anstatt 
des Betriebssystems das Schlsselwort DEL steht. Die Zeile

#M H, #T OEPT, #S DEL, #D H-TOS.FLS

leitet also alle Lschinformationen, die den PT @ H betreffen, explizit 
in die Datenbank H-TOS.FLS. Beim speziellen Betriebssystem DEL ist der 
Operator ` nicht zulssig.

--------------------------
4.4 Die minimale INF-Datei
--------------------------

Die minimale INF-Datei besteht aus nur zwei Zeilen: Die erste enthlt das 
Schlsselwort #Gruppen, die zweite einen beliebigen Gruppennamen. Diese 
Angaben sind Pflicht, weil es keinen Sinn macht, Stber zu benutzen, wenn 
man nicht wenigstens eine Gruppe durchsuchen lt.

Was tut Stber nun mit dieser minimalen INF-Datei?

Nun, das Logfile heit standardmig STOEBER.LOG und wird im aktuellen 
Verzeichnis angelegt. Als Outfile wird OUTFILE.TXT im aktuellen 
Verzeichnis angenommen, Pfad und Name knnen Sie aber auch ber die 
Kommandozeilenoption -o einstellen. Die erzeugte Stapeldatei heit 
STAPEL.DAT und befindet sich ebenfalls im aktuellen Verzeichnis. Weil 
nichts gegenteiliges angegeben ist, werden alle Filelisten-Eintrge, die 
in der durchsuchten Gruppe gefunden werden, in die Stapeldatei bernommen.

-------------
5. OUT-Blcke
-------------

Bei neueren MAUS-Versionen knnen Sie ber MausTausch-Kommandos Filelisten 
von der Maus anfordern. Diese bekommen Sie nicht als PM geschickt und auch 
nicht als separate Datei, sondern sie stehen in speziellen Blcken inner-
halb des Outfiles.

Diese Blcke haben jeweils eine Kennung, die mit OUT beginnt und noch von 
vier Buchstaben, beginnend mit AAAA, vervollstndigt wird. Das Frontend 
CAT legt solche Blcke beim Einfgen des Outfiles bespielsweise unter dem 
Namen OUTAAAA.TXT im Datenbankordner ab.

Stber erkennt nun derartige Blcke automatisch und behandelt deren Inhalt 
genau wie Mitteilungen in den zu durchsuchenden Gruppen. Dabei mssen die 
Listen in einem der Formate "Ausfhrliche Liste" oder "Kurzliste" angefor-
dert worden sein und vom PT oder einem GPT stammen (also nicht aus dem 
Persnlichen Programmteil).

--------------------------
6. Gesplittete Nachrichten
--------------------------

Noch vor einiger Zeit war es an der Tagesordnung, inzwischen ist es sehr 
viel seltener geworden:

Gelegentlich werden Mitteilungen ber neue Dateien, die die zulssige 
Nachrichtenlnge berschreiten, mitten im Text unverhofft gesplittet, 
obwohl die verantwortliche Software eigentlich in der Lage ist, ein 
"sauberes" Splitting vorzunehmen, soda in der Folgenachricht ein neuer 
Header steht und Filelisten-Eintrge immer komplett in einer Nachricht 
bleiben.

Stber kommt zwar auch mit "unsauberen" Splittings weitgehend zurecht, 
allerdings wird von auseinandergerissenen Filelisten-Eintrgen oder 
(wichtiger) Lschblcken jeweils nur der erste Teil ausgewertet.

Von Stber erkannte "unsaubere" Splittings werden grundstzlich in einer 
Zeile im Logfile vermerkt.

----------
7. Autoren
----------

Idee, Programmierung und Copyright 1995-1997:

        Adrian Reyer
        Schalksburgstr. 240
        D-72458 Albstadt
        Tel. 07431-74595
        Adrian Reyer @ BL

Aktuelle Version, Weiterentwicklung und Copyright 1998:

        Jens Brggemann
        Reuterdamm 122
        D-30853 Langenhagen
        Tel. 0511-721751
        Jens Brggemann @ H

----------
8. Haftung
----------

Niemand garantiert irgendwas, die Benutzung geschieht auf eigene Gefahr.

------------
9. Sonstiges
------------

Stber liefert einen Returncode an seinen Aufrufer zurck. Dieser ist 
im Normalfall 0, bei Auftreten eines Fehlers 1.

Die Uhrzeiten im Logfile werden nach GEMDOS-Einschrnkungen nur mit 
2 Sekunden Genauigkeit ausgegeben. Eine Laufzeit von 0 Sekunden wre 
also nur eine Illusion. :-)

