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.


Umschalten auf eine andere Sprache
==================================

Da  inzwischen  alle Ausgaben in RSC- und String-Dateien ausgelagert wurden, ist
es  mglich,  SETTER auf eine andere Sprache umzustellen. Dazu mu lediglich die
gewnschte Sprachdatei SETTER_?.STR in SETTER.STR umbenannt werden.
Folgende Sprachen sind derzeit vorhanden:
    SETTER_G.STR    deutsche Ausgaben
    SETTER_E.STR    englische Ausgaben
Die  Resourcedateien  drfen  nicht  umbenannt werden. Welche Resourcen zu laden
sind ist in der jeweiligen Stringdatei festgelegt.
    SETTER_G.STR --> SETTER.STR ===> automatisch wird SETTER_G.RSC geladen
    SETTER_E.STR --> SETTER.STR ===> automatisch wird SETTER_E.RSC geladen


Implementierung einer neuen Sprache
===================================

Zunchst kopiere man SETTER_G.STR und SETTER_G.RSC und bennene diese um, z.B. in
SETTER_F.STR   und  SETTER_F.RSC  fr franzsisch. Nun knnen die beiden Dateien
mit  einem normalen Resourcen-Editor verndert werden. Der erste String nach den
Alerts  in SETTER_?.STR gibt den Namen der RSC-Datei wieder und ist entsprechend
zu ndern.


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.

10. Dezember 1993
    - Bei Zeichenketten wird wie bei allen anderen Werten im Fenster nun auch
      ein senkrechter Strich zur Abtrennung angezeigt.
    - Bei der Ausgabe als C-Source war ein Fehler in der Anzahl der
      Listenelemente bei SETTERLIMITWORDS und SETTERLIMITLONGS. Es wurden
      immer von genau zwei Elementen zuviel ausgegangen.
    - Redrawoptimierung rausgeworfen, weil es beim Scrollen ber die Maus
      unter Umstnden sonst zu seltsamen Effekten kommt.
    - Fehlermeldungen bei Bereichsberschreitung wird nicht nun nicht nur
      zusammengebaut sondern auch ausgegeben.
    - Bei der Ausgabe als C-Source werden nun auch Anfhrungszeichen und
      Backslash korrekt behandelt.
    - Die Ausgabe als S-Source setzt nun zustzliche Labels wie beim C-Source.
    - C-Source- und S-Source-Ausgaben insgesamt verbessert.

15. Dezember 1993
    - Fehler in der Darstellung der Titelboxen, der sich neu eingeschlichen
      hatte, wieder behoben.
      (gemeldet von Manfred Vogel)

22. Dezember 1993
    - Fehler in der Cursorpositionierung mit der Maus behoben. Es wurde
      relativ zur ersten Datenzeile insgesamt positioniert. Nun wird korrekt
      relativ zur ersten angezeigten Datenzeile positioniert.
      (gemeldet von Thorsten Wollweber)

6. April 1994
    - Soweit dies mglich war, sind nun die Texte aller ausgegebenen Meldungen
      in die RSC-Datei verlagert. Damit sollte eine fremdsprachige Version
      sehr viel leichter zu erstellen sein.


8. April 1994
    - Da auf Grund obiger nderung kein Batch-Betrieb mehr mglich war,
      schlielich mute SETTER.RSC immer geladen werden, wurde das Konzept
      nochmals gendert. Die freien Strings sind nun in einer getrennten Datei
      abgelegt, die unabhngig vom AES geladen wird.
      Diese Datei wird im aktuellen Verzeichnis und ber die
      Environmentvariablen SETTER (Suchpfad!) und PATH gesucht.


(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.
