USERLIST.PRG V1.02                           (c) 10.04.1994 by Jrgen Meyer
==================


Dieses External bentigt das Mad-Sys ab Version V4.05.R1
--------------------------------------------------------


Update V1.02 (von V1.01):

- Neuer Wert wird bergeben (Flag, ob User in Userlisten sichtbar ist
  oder nicht). Siehe Erklrung im Text bei betreffenden Absatz.


Update V1.01 (von V1.00):

- Neuer Kommandoblock "$" eingefhrt, siehe Erklrung im Text



Userlist dient dazu, die Daten aller im System eingetragener User externen
Anwendungen (Externals) zur Verfgung zu stellen. Es werden dabei alle
relevanten Daten ausgegeben. Somit knnen Externals nun Datenbestnde
aufbauen oder Informationen einlesen, ohne auf die codierte SYSTEM.DAT
zugreifen zu mssen, dessen Format ich bekanntlich nicht dokumentiere.

Userlist erzeugt im Ordner \TEXTE eine Datei namens "USERLIST.TXT", die
im sogenannten "Maschinenlesbaren Format" abspeichert ist. Will sagen: es
ist NICHT VORGESEHEN, diese Datei einfach dem User anzuzeigen, sondern
die Informationen sind so kodiert, da sie mittels eine simplen Routine
leicht und einfach verarbeitet werden knnen.

********************************************************************
* Bitte diese Datei NIEMALS irgendwelchen Usern zugnglich machen! *
* Es sind Informationen enthalten, die nur SysOps etwas angehen!   *
********************************************************************

Userlist mu als External vom Mad-Sys gestartet werden, es kann in allen
mglichen Positionen in EXTERNAL.DAT eingetragen werden. Der Start via
MENUE.DAT oder von der Shell aus ist ebenfalls mglich. Vom DeskTop aus
kann Userlist NICHT gestartet werden.

Userlist ttigt folgende Aktionen:

1. MB.INF einlesen
2. SYSTEM.DAT einlesen
3. USERLIST.TXT schreiben

Es mu gengend Speicher vorhanden sein, um SYSTEM.DAT einlesen zu knnen
und um die Datei USERLIST.TXT aufzubereiten. USERLIST.TXT wird im Speicher
erzeugt und als Block weggespeichert, um hchstmachbare Geschwindigkeit zu
erreichen.

Evtl. Fehler schreibt Userlist in das Logbuch. Kann die Datei MB.INF nicht
gelesen werden, wird ein Fehler -33 zurckgegeben. Fehler 1 passiert, wenn
die bergebenen Parameter nicht gltig sind, Fehler 2, wenn das verwendete
Mad-Sys lter als V4.02.R1 ist.

Userlist bentigt in etwa genauso viel Zeit, wie ein "UL" Aufruf (Zeit,
bis die Userliste aufgebaut ist, siehe Sternchen-Balken). Bei vielen Usern
kann es daher schon mal 10-20 Sekunden dauern (normaler 16 MHz - Atari).
Insofern sollte man es, sofern als Zeitexternal installiert, nicht zu hufig
starten.

Userlist berschreibt bei jedem Aufruf die Datei USERLIST.TXT aufs Neue.

USERLIST.TXT ist eine normale ASCII-Datei mit maximal 79 Zeichen pro Zeile,
derzeit wird dieses Maximum noch nicht ganz ausgenutzt. Alle Zeilen werden
mit dem blichen CR+LF ($0D, $0A) beendet. Zeilen, die mit einem ";" an-
fangen sind Kommentarzeilen und drfen nicht ausgewertet werden. Die Datei
wird mit dem bekanntem "*** END ***" beendet.


Das Format von USERLIST.TXT
---------------------------

USERLIST.TXT kennt derzeit drei Kommandoblcke. Der Erste wird mit einem
"=" als erstes Zeichen in der Zeile eingeleitet und ist grundstzlich
die erste auszuwertende Zeile in der Datei.

Beispiel fr einen Header von USERLIST.TXT:

; Maschinenlesbare Userliste vom 16.08.1993 um 20:35:40
;
; Version V1.02
;
=0102 1B10 A474
;

In den ersten Kommentarzeilen erscheint nur eine Info, wann die Datei
erzeugt wurde und um was es sich handelt. Ebenso eine klarschriftliche
Angabe der Versionsnummer.

Die erste auszuwertende Zeile beginnt, wie bereits erwhnt, mit einem
"=". Gefolgt vom = ist die VERSIONSNUMMER der Datei in Hexadezimal codiert.
Hier wird immer ein 16-bit Wort unsigned angegeben, wobei das Highbyte
die Manor-Versionsnummer, das Lowbyte die Minor-Versionsnummer darstellt.
Wre die Versionsnummer "V1.08", so wrde da stehen: "=0108".

**********************************************************************
* Bitte als Programmierer UNBEDINGT die Versionsnummer auswerten!!!  *
* Die Datei USERLIST.TXT *NUR*DANN* bearbeiten, wenn die Versions-   *
* nummer Eurem Programm bekannt ist, d.h. ein Vergleich identisch &  *
* "wahr" ist. Andernfalls knnen SCHWERE Schden auftreten in Euren  *
* Daten, oder User kommen an Daten ran, die sie nicht sehen sollten! *
**********************************************************************

Alle Werte in jeder Zeile werden durch EIN Leerzeichen getrennt. Im Falle
der "=" Zeile erscheint nach der Versionsnummer noch das Datum gefolgt von
der Zeit, wann die Datei USERLIST.TXT erzeugt wurde (Info zum Datum/Zeit-
Format siehe unten).

ALLE Werte werden in Hexadezimal-Schreibweise ausgegeben. Es gibt KEINE
Ausnahmen!


Aufbau des Kommandoblocks "$"
-----------------------------

Die Zeile, die mit "$" beginnt, enthlt Informationen ber die Anzahl
der User. Somit kann diese Zeile erst ausgewertet, entsprechend viel
Speicher reserviert/Arrays dimensioniert werden, bevor die eigentlichen
Userdaten eingelesen werden. Eine typische $-Zeile sieht so aus:

;
$0081 0002 0005
;

Der erste Wert (direkt nach dem $) gibt an, wieviele User es gesamt
im System gibt. Der zweite sagt aus, wieviel User davon "Deaktiviert"
sind (siehe Mad-Sys Anleitungen). Der dritte Wert zeigt an, wieviele
User von der Gesamtzahl "Neue User" sind (siehe Update-README zur
V4.xx).


Aufbau eines Eintrags fr einen User
------------------------------------

Ein typischer Eintrag fr einen User in USERLIST.TXT sieht so aus:

;
:0188 000001C2 BetaUser                                 00000002 1AF4 AA1C
 1AF4 AA2E 1AF4 A910 1AF4 000000E3 09E1 00000001 00 00 00 05 00 18 00 00 01
 0064 01 84 94 81 8E 99 9A 9E 00
;

Jeder User belegt drei Zeilen. Mchte ein External nur auf ausgewhlte
User, und nicht alle User zugreifen, so kann es sich anhand der ":" in der
Ersten der drei Parameterzeilen orientieren. Die ERSTE Zeile eines User-
eintrags beginnt immer mit einem ":", die beiden nachfolgenden haben ein
Space (Leerzeichen) an erster Stelle.

Nachfolgend der Aufbau der drei Zeilen sowie die Bedeutung der Werte.


Erste Zeile
-----------

:0188 000001C2 BetaUser                                 00000002 1AF4 AA1C
 -+-- ---+---- -------------------+-------------------- ---+---- -+-- -+--
  |      |                        |                        |      |    |
  1      2                        3                        4      5    6

Wert  1: Usernummer (minimal 1, maximal 10000 (dezimal))
Wert  2: Eindeutige User-ID (Achtung: 32 bit, ein Langwort!)
Wert  3: Der Name in ASCII des Users. Die ist die einzige Abweichung
         zum "Werte-Standard". Der Name wird immer 40-Zeichen lang aus-
         gegeben, ist der Username weniger als 40 Zeichen lang, wird mit
         Spaces (Leerzeichen) aufgefllt. Nach den 40 Zeichen kommt kon-
         sequenterweise natrlich das Trennungs-Leerzeichen!
Wert  4: Anzahl der Anruf des Users (Langwort)
Wert  5: Datum des User-Neueintrags (Info siehe Ende des Textes)
Wert  6: Zeit des User-Neueintrags  (Info siehe Ende des Textes)


Zweite Zeile
------------

 1AF4 AA2E 1AF4 A910 1AF4 000000E3 09E1 00000001 00 00 00 05 00 18 00 00 01
 -+-- -+-- -+-- -+-- -+-- ---+---- -+-- ---+---- +- +- +- +- +- +- +- +- +-
  |    |    |    |    |      |      |      |     |  |  |  |  |  |  |  |  |
  7    8    9    10   11     12     13     14    15 16 17 18 19 20 21 22 23

Wert  7: Datum des letzten Logins (Info siehe Ende des Textes)
Wert  8: Zeit des letzten Logins  (Info siehe Ende des Textes)
Wert  9: Datum des letzten "NE"-Aufrufes (Info siehe Ende des Textes)
Wert 10: Zeit des letzten "NE"-Aufrufes  (Info siehe Ende des Textes)
Wert 11: Datum des letzten Passwort-Wechsels (Info siehe Ende des Textes)
Wert 12: Bisherige gesamte Onlinezeit des Users in Sekunden seit Ersteintrag
Wert 13: 16-bit Wort fr 16 mgliche Userparameter (siehe Funktion "PAR").
         Eine Erklrung dazu ist im Text \_MANUAL\STRUKTUR.EN\PARA_EXT.TXT
         zu finden.
Wert 14: Hier wird/werden der/die vom User eingestellte(n) Rechner angegeben.
         Um diesen Wert in Klarschrift zu lesen, mu die Datei "URECHNER.DAT"
         im Ordner \SYSTEM eingelesen werden. URECHNER.DAT ist in die IDs
         0 (Null) bis 31 aufgeteilt. Reprsentativ ist hier das jeweilige
         Bit (Bit 0 bis 31, ein Langwort) gesetzt, wenn der User den jewei-
         ligen Rechner mit der entsprechenden ID angewhlt hat oder nicht.
Wert 15: Flag. Wenn dieses Byte 0 ist, dann handelt es sich um einen nor-
         malen, besttigten User. Ist das Byte ungleich 0, ist es ein neuer
         User, der noch nicht mit CUD S (Status ndern) "bearbeitet" wurde.
Wert 16: Flag. Ist dieses Byte 0, so kann der User beim nchstem Passwort-
         Wechsel ruhig sein altes PW wieder verwenden. Ist dieses Byte aber
         ungleich 0, so wird der User gezwungen, ein anderes PW als das bis-
         herige einzugeben.
Wert 17: Flag. Ist dieses Byte 0, so handelt es sich um einen normalen, ak-
         tiviertem User. Ist dieses Byte ungleich 0, so ist der User deak-
         tiviert und kann sich auch nicht einloggen.
Wert 18: Hier wird der Status des Users (0 bis 9) angegeben.
Wert 19: In diesem Byte wird die eingestellte Terminalemulation des Users
         abgelegt. Mglich sind derzeit folgende Werte:

         0 = Keine Emulation
         1 = VT 52 Emulation
         2 = VT 100/102 / ANSI Emulation

Wert 20: Hier werden die Anzahl der Zeilen bis zum Seitenstop (sofern vom
         User eingeschaltet, kann mit Wert 13 ermittelt werden) gespeichert.
Wert 21: Dieses Byte gibt die Gebhrentarifszone an. Diese kann von 0 bis
         4 reichen, je nachdem, in welchem Land das Mad-Sys betrieben wird.
Wert 22: Flag. Ist dieses Byte 0, so kann sich der User normal ber alle
         Schnittstellen einloggen. Ist dieses Byte ungleich 0, so ist ein
         Login des jeweiligen Users nur ber die MIDI-Schnittstelle sowie
         die Console mglich.
Wert 23: Flag. Ist dieses Byte 0, so hat der User das Krzelmenue (Eingabe
         von Befehlen) selektiert. Ist das Byte ungleich 0, so wurde das
         Cursormenue vom User eingeschaltet.


Dritte Zeile
------------

 0064 01 84 94 81 8E 99 9A 9E 00
 -+-- +- +- +- +- +- +- +- +- +-
  |   |  |  |  |  |  |  |  |  |
  24  25 26 27 28 29 30 31 32 33

Wert 24: Dieses 16-bit Wort gibt an, um wieviel Prozent die Systemzeit des
         Users erhht oder erniedrigt wird. Folgende Bereiche gibt es:

           1 -   99  Es werden 1% bis 99% von der regulren Systemzeit
                     ABGEZOGEN
                100  Der User hat die normale Systemzeit, also +/- 0%
         101 - 1100  Der User erhlt 1% bis 1000% mehr Systemzeit, also
                     ZUGERECHNET

Wert 25: Flag. Ist dieses Byte 0, so hat der User die Umlautwandlung aus-
         geschaltet, d.h. alle Umlaute werden nach ae, oe, ue etc. gewan-
         delt. Ist dieses Byte ungleich 0, so wird eine Umlautwandlung nach
         den vom User eingestellten Umlauten vorgenommen.
Wert 26: Byte. ASCII-Code fr den Umlaut "" (kleines a-Umlaut) des Users.
Wert 27: Byte. ASCII-Code fr den Umlaut "" (kleines o-Umlaut) des Users.
Wert 28: Byte. ASCII-Code fr den Umlaut "" (kleines u-Umlaut) des Users.
Wert 29: Byte. ASCII-Code fr den Umlaut "" (groer A-Umlaut) des Users.
Wert 30: Byte. ASCII-Code fr den Umlaut "" (groer O-Umlaut) des Users.
Wert 31: Byte. ASCII-Code fr den Umlaut "" (groer U-Umlaut) des Users.
Wert 32: Byte. ASCII-Code fr den Umlaut "" (scharfes s (sz)) des Users.
Wert 33: Flag. Ist dieses Byte gleich 0, so ist der User normal sichtbar
         in allen von der Box erzeugten Userlisten. Ist das Byte ungleich
         0, so wird der User "versteckt", d.h. in keiner Userliste ange-
         zeigt.



Erklrungen zu Datum & Zeit als Wort
------------------------------------

Das Mad-Sys speichert Datum & Zeit immer im GEMDOS-Format. In diesem Format
wird jeweils das Datum und die Uhrzeit in ein 16-bit unsigned Wort verpackt.
Folgend eine Aufschlssung der beiden Wrter:

Datum     Bit  0 -  4   Tag (0-31)
          Bit  5 -  8   Monat (1-12)
          Bit  9 - 15   Jahr (0-119)    --> Zu diesem Wert immer "1980"
                                            addieren!

Zeit      Bit  0 -  4   Sekunde (0-29)  --> Dieser Wert immer mit 2 multipli-
                                            zieren!
          Bit  5 - 10   Minute (0-59)
          Bit 11 - 15   Stunde (0-23)


MfG. Jrgen Meyer

