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 natrlich in keinster Weise fr irgendwelche Auswirkungen oder 
Nichtwirkungen, die der Einsatz oder Nichteinsatz von SETTER.* hat. Es ist 
zwar nicht sehr wahrscheinlich, aber durchaus m”glich, daž SETTER irgendwelche 
Daten vernichtet, die fr Sie essentielle Bedeutung haben!

Originalton Harun:

M”glicherweise finden auch andere Programmierer SETTER ntzlich, bitte, 
ihr drft 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 erwnscht, 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 Erkl„rung versehen. Bei residenten
Programmen liegen diese Erkl„rungen natrlich im nichtresidenten Teil (kein
Problem bei Assemblerprogrammierung). Konfiguriert werden solche Programme
mit SETTER, das die Informationen und Erkl„rungen 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-Oberfl„che mit 
Menzeile. U.U. ”ffnen sich gleich ein paar Fenster, n„mlich falls Dateinamen 
bergeben wurden.


Das Men
========

Die Tastaturkrzel im Men k”nnen mit Hilfe eines RSC-Kontruktion-Sets 
ge„ndert werden. Es ist lediglich zu beachten, daž dem Krzel kein Leerzeichen 
mehr folgen darf.

SETTER
------
  Hier findet sich nur der Menpunkt < šber SETTER ... >, der sich selbst 
  erkl„rt.

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.

< Schliežen >
  Der oberste Konfigurationsblock wird freigegeben. Wurden Žnderungen daran 
  vorgenommen, so erfolgt eine Sicherheitsabfrage, ob er nicht zun„chst 
  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 šberprfung, ob diese Datei berhaupt einen Konfigurationsblock mit 
  identischen Aufbau besitzt. Ist das nicht der Fall, verweigert SETTER die 
  Zerst”rung 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 fr eine 
  Variable setterblk von genau diesem Typ gespeichert und aužerdem die 
  zugeh”rige C-Headerdatei.
  Befinden sich in den Erkl„rungen Strings, die mit einem # beginnen und 
  maximal 10 Zeichen enthalten, die einen gltigen C-Bezeichner darstellen, so 
  werden in der C-Headerdatei Untertypen damit benannt.

< Beenden >
  Alle offenen Konfigurationsbl”cke werden geschlossen und SETTER beendet.


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

Die Fenster sind normal bedienbar. Das oberste Fenster kann aužer 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 ge„ndert 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 Ausfhrung 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


(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 ver„ndern 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

Enth„lt 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 n„chste 
gerade Adresse evtl. mit einem zus„tzlichen 0-Byte aufgefllt. Ist der 
Anzeigestring leer (nur 0-Byte), so endet hier die Liste der Objekte.

Das Konfigurationskommando ist ein WORD (16Bit) mit folgenden m”glichen 
Werten im Highbyte:

0
Ja/Nein Entscheidung. Das folgende WORD wird fr JA auf $FFFF und fr 
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 ungltig-Kennung fr einen Platz ist $80000000.

2
String-Eingabe. Im Lowbyte steht die Maximall„nge des Eingabestrings 
inklusive des abschlieženden Nullbytes. Diese L„nge muž gerade sein. Der 
eingegebene String wird unmittelbar hier hinter abgelegt und bis zur 
Maximall„nge mit 0-Bytes aufgefllt.

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 ungltig-Kennung fr einen Platz ist $8000.

4
Derzeit nicht verwendet, aber fr 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 ungltig-Kennung fr einen Platz ist
$80000000, darf aber nur verwendet werden, wenn dies im Wertebereich liegt.

6
Datei- oder Pfadname. Entspricht grunds„tzlich 2, jedoch ist die L„nge auf 
maximal 128 Byte beschr„nkt und im Stringdialog ist zus„tzlich der Aufruf 
einer Dateiauswahlbox m”glich.

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 ungltig-Kennung fr einen Platz ist
$8000, darf aber nur verwendet werden, wenn dies im Wertebereich liegt.

Das war's bisher.