SETTER.PRG, ein Konfigurator
****************************

Copyright
=========

SETTER.PRG darf zusammen mit diesem Text frei kopiert werden, soweit die 
Bedingungen aus der Info-Box < SETTER | ber Setter ... | Info > befolgt 
werden.

Ich hafte natrlich in keinster Weise fr irgendwelche Auswirkungen oder 
Nichtwirkungen, die der Einsatz oder Nichteinsatz von SETTER.* hat. Es ist 
zwar nicht sehr wahrscheinlich, aber durchaus mglich, da SETTER irgendwelche 
Daten vernichtet, die fr Sie essentielle Bedeutung haben!

Originalton Harun:

Mglicherweise finden auch andere Programmierer SETTER ntzlich, bitte, 
ihr drft es benutzen. Aber!:
Wenn jemand eine erweiterte Version von SETTER in Umlauf bringt, mu:
- diese ebenfalls frei kopierbar sein.
- diese entsprechend gekennzeichnet sein.
- er mir eine Nachricht, besser ein Exemplar, kostenlos zukommen lassen.
Ich kann es nicht ausstehen, wenn jemand meine Spezifikation ndert. 
Erweitern ist erlaubt und erwnscht, aber bitte keine bereits vorhandenen 
Kommandos ndern.

"Ich" bin: Harun Scheutzow,
zu erreichen im Internet ber
Harun_Scheutzow@B.maus.de
bzw. im Mausnetz: Harun Scheutzow @B

Ende des Originaltons.


SETTERs Sinn und Zweck:
=======================

Die kleinen ASCII-Textfiles, mit denen viele Programme konfiguriert werden,
sind Harun auf die Nerven gegangen. Sie haben zwar den Vorteil der
nderbarkeit mit jedem Texteditor, liegen als Nachteil aber mit im
Verzeichnis rum und sind trotzdem oft nicht da, wo sie sein sollten.

Deshalb hat er die Konfigurationsinformationen direkt im Programm
untergebracht und mit einer kurzen Erklrung versehen. Bei residenten
Programmen liegen diese Erklrungen natrlich im nichtresidenten Teil (kein
Problem bei Assemblerprogrammierung). Konfiguriert werden solche Programme
mit SETTER, das die Informationen und Erklrungen aus dem Programm liest und
die Konfiguration wieder im Programm speichert.


Nutzung
=======

Entweder man zieht das zu bearbeitende Programm mit der Maus auf 
SETTER.PRG oder ruft SETTER von einer Shell mit einer Befehlszeile auf oder 
startet es durch Doppelklick. Ob Programm wirklich konfigurierbar sind, 
erkennt SETTER mit hoher Sicherheit automatisch.

In der Befehlszeile sind folgende Kommandos erlaubt, die entsprechende ihrer 
Reihenfolge abgearbeitet werden:
  -I:<datei>
    Programm oder Setterblockdatei laden.
  -E:<datei>
    Obersten Konfigurationsblock in die Datei speichern.
  -C
    Obersten Konfiguationsblock freigeben.
  -C:<datei>
    Konfigurationsblock, der aus der angegebenen Datei geladen wurde, freigeben.
Beispiel:
  -I:Datei1.PRG -E:Datei1.BLK -I:Datei2.PRG -C:Datei1.PRG -C
  1. Datei1.PRG lesen
  2. Den gelesenen Konfigurationsblock aus Datei1.PRG nach Datei1.BLKL 
     speichern
  3. Datei2.PRG lesen
  4. Den Konfigurationsblock von Datei1.PRG vergessen
  5. Den obersten Konfigurationsblock - das ist der aus Datei2.PRG - vergessen

Wurde SETTER ohne Kommandos gestartet, so erscheint eine GEM-Oberflche mit 
Menzeile. U.U. ffnen sich gleich ein paar Fenster, nmlich falls Dateinamen 
bergeben wurden.


Das Men
========

Die Tastaturkrzel im Men knnen mit Hilfe eines RSC-Kontruktion-Sets 
gendert werden. Es ist lediglich zu beachten, da dem Krzel kein Leerzeichen 
mehr folgen darf.

SETTER
------
  Hier findet sich nur der Menpunkt < ber SETTER ... >, der sich selbst 
  erklrt.

Datei
-----

< ffnen ... >
  ber eine Dateiauswahl kann ein Konfigurationsblock aus einem Programm oder 
  einem gespeicherten Setterblock eingelesen werden. Es ffnet sich dann ein 
  Fenster, in dem die Konfiguration angezeigt wird.

< Schlieen >
  Der oberste Konfigurationsblock wird freigegeben. Wurden nderungen daran 
  vorgenommen, so erfolgt eine Sicherheitsabfrage, ob er nicht zunchst 
  gesichtert werden soll.

< Sichern >
  Der oberste Konfigurationsblock wird in die Datei gespeichert, aus der er 
  stammt.

< Sichern als ... >
  Der oberste Konfigurationsblock kann in eine andere oder eine neue Datei 
  gespeichert werden. Wird in eine existierende Datei gespeichert, so erfolgt 
  eine berprfung, ob diese Datei berhaupt einen Konfigurationsblock mit 
  identischen Aufbau besitzt. Ist das nicht der Fall, verweigert SETTER die 
  Zerstrung der Datei.
  Wird in eine neue Datei gespeichert, so wird in dieser nur der 
  Konfigurationsblock mit einer vorangestellten Kennung gespeichert.
  Besitzt die Datei die Endung ".C", ".H" oder ".S", so tritt ein Sonderfall 
  in Aktion. Bei ".S" wird eine Assemblersourcedatei mit dem 
  Konfigurationsblock gespeichert; bei ".H" eine C-Headerdatei mit der 
  Definition eines Types SETTERBLK, der im Aufbau genau dem 
  Konfigurationsblock entspricht. Bei ".C" wird eine Initialisierung fr eine 
  Variable setterblk von genau diesem Typ gespeichert und auerdem die 
  zugehrige C-Headerdatei.
  Befinden sich in den Erklrungen Strings, die mit einem # beginnen und 
  maximal 10 Zeichen enthalten, die einen gltigen C-Bezeichner darstellen, so 
  werden in der C-Headerdatei Untertypen damit benannt.

< Beenden >
  Alle offenen Konfigurationsblcke werden geschlossen und SETTER beendet.


Fensterbedienung
================

Die Fenster sind normal bedienbar. Das oberste Fenster kann auer mit der 
Maus auch ber verschiedene Tasten bedient werden. Durch Anklicken einer 
Zeile, wird der Cursor sichtbar. Dieser kann dann mit den Cursortasten AUF und 
AB verschoben werden. Mit LINKS und RECHTS wird der Fensterinhalt nach links 
und rechts verschoben. Mit SHIFT-LINKS und SHIFT-RECHTS gelangt man an den 
Anfang bzw. das Ende des darstellbaren Bereichs, mit CTRL-LINKS und 
CTRL-RECHTS seitenweise nach links bzw. rechts.

Durch Doppelklick oder mit Enter/Return wird zur entsprechenden Zeile eine 
Dialogbox angezeigt. In dieser kann die Konfiguration gendert werden.

Das war schon alles in der Bedienung.


Danksagung:
===========

Mein Dank gilt Harun Scheutzow, der zwar des fteren eine andere Auffassung 
als ich vertritt, aber dennoch immer wieder ganz brauchbare Ideen hat. Vom ihm 
stammt die Idee und erste Ausfhrung von SETTER (als kleines TTP).


Versionen
=========

In der Dialogbox ber Setter < SETTER | ber SETTER ... > wird ein Datum 
angezeigt. Dieses gibt an Stelle einer Versionsnummer die Version wieder. Bei 
Fragen und Problemen sollte dieses Datum mit angegeben werden.

Ich bin im MausNet per e-mail erreichbar:
Markus Kohm @ KA2
oder via Internet: 
Markus_Kohm@KA2.maus.de


6. Dezember 1993
    - erste freigegebene Version

9. Dezember 1993
    - Wird ein einzelnes Fenster in den Hintergrund gelegt, wurde das Fenster 
      versehentlich aus der internen Fensterliste gelscht.
      (gemeldet von Manfred Vogel)
    - Genereller Redrawfehler bei den Dialogboxen, wenn Let 'em Fly nicht 
      verwendet wurde.
    - Zeitweiliger Redrawfehler bei den Dialogboxen, wenn Let 'em Fly nicht 
      verwendet wurde.


(Der reine Anwender braucht nicht weiter zu lesen.)
Spezifikation des Speicherns modifizierbarer Informationen in Programmen
========================================================================

Original von Harun Scheutzow, 21.11.1993
erweitert von Markus Kohm, 06.12.1993


Die Modifikation erfolgt durch ein SETTER.TTP oder SETTER.PRG, welches das
Programm bearbeitet, dessen Einsstellungen zu verndern sind.

Im TEXT- oder DATA-Segment befindet sich auf einer geraden Adresse der 
nullterminierte String "hAruNs cONfigER" (inklusive 0-Byte genau 16 Zeichen 
lang) und dahinter ein LONG-Zeiger auf den Anfang des Strings. In 
Assembler:

      .even
hkbg:
      .dc.b "hAruNs cONfigER",0
      .dc.l hkbg

Enthlt die Datei lediglich einen Setterblock, ohne ein Programm zu sein, so 
beginnt sie mit:

      .dc.b "MaRkus cONfigER",0

Darauf folgen als Liste die einzelnen Objekte, die aus Anzeigetext, 
Art der Konfiguration und Konfigurationsplatz bestehen.

Der Anzeigetext ist ein C-String (also nullterminiert) und auf die nchste 
gerade Adresse evtl. mit einem zustzlichen 0-Byte aufgefllt. Ist der 
Anzeigestring leer (nur 0-Byte), so endet hier die Liste der Objekte.

Das Konfigurationskommando ist ein WORD (16Bit) mit folgenden mglichen 
Werten im Highbyte:

0
Ja/Nein Entscheidung. Das folgende WORD wird fr JA auf $FFFF und fr 
NEIN auf $0000 gesetzt.

1
LONG-Werteingabe-Liste. Im Lowbyte steht die Anzahl der Listenelemente. 
Die folgenden LONG werden auf die Werte der eingegebenen 32-Bit-Integer 
gesetzt. Die interne ungltig-Kennung fr einen Platz ist $80000000.

2
String-Eingabe. Im Lowbyte steht die Maximallnge des Eingabestrings 
inklusive des abschlieenden Nullbytes. Diese Lnge mu gerade sein. Der 
eingegebene String wird unmittelbar hier hinter abgelegt und bis zur 
Maximallnge mit 0-Bytes aufgefllt.

3
WORD-Werteingabe-Liste. Im Lowbyte steht die Anzahl der Listenelemente.
Die folgenden WORD werden auf die Werte der eingegebenen 16-Bit-Integer 
gesetzt. Die interne ungltig-Kennung fr einen Platz ist $8000.

4
Derzeit nicht verwendet, aber fr mich reserviert.

5
LONG-Werteingabe-Liste mit Wertbereichseingrenzung. Im Lowbyte steht die
Anzahl der Listenelemente. Bevor nun die Liste wie bei 1 kommt, folgen zwei
LONG, welchen die untere und obere Grenze des erlaubten Wertebereichs
bestimmen. Die folgenden LONG werden auf die Werte der eingegebenen
32-Bit-Integer gesetzt. Die interne ungltig-Kennung fr einen Platz ist
$80000000, darf aber nur verwendet werden, wenn dies im Wertebereich liegt.

6
Datei- oder Pfadname. Entspricht grundstzlich 2, jedoch ist die Lnge auf 
maximal 128 Byte beschrnkt und im Stringdialog ist zustzlich der Aufruf 
einer Dateiauswahlbox mglich.

7
WORD-Werteingabe-Liste mit Wertbereichseingrenzung. Im Lowbyte steht die
Anzahl der Listenelemente. Bevor nun die Liste wie bei 3 kommt, folgen zwei
WORD, welchen die untere und obere Grenze des erlaubten Wertebereichs
bestimmen. Die folgenden WORDwerden auf die Werte der eingegebenen
16-Bit-Integer gesetzt. Die interne ungltig-Kennung fr einen Platz ist
$8000, darf aber nur verwendet werden, wenn dies im Wertebereich liegt.

Das war's bisher.
