(english doc is at bottom of text)
RSH2RSI - GEM Ressource-Konverter V1.2
--------------------------------------
GEM  bietet  mit  seiner Mglichkeit,  per RCS  (Ressource  Construction  Set) 
einfach  am  Bildschirm Dialogboxen,  Mens etc.  zu  erstellen,  eine  starke 
Vereinfachung  bei der Programmierung von Bildschirmdialogen.
  Diese fr den Programmierer einfache Handhabung hat aber auch Nachteile:  zu 
jedem GEM-Programm wird eine entsprechende Ressource-Datei bentigt,  die  bei 
jedem Programmstart geladen wird.  Dies bereitet besonders dann Probleme, wenn 
das Programm nicht aus dem aktuellen Verzeichnis gestartet wurde  (z.B.  indem 
das  Programm  per 'Anwendung anmelden' und Doppelklick auf  eine  Daten-Datei 
gestartet wird) - dann wird die Ressource-Datei nicht gefunden.  Bei  Accesso-
ries  verzgert sich der Bootvorgang durch das Nachladen der Ressourcen  nicht 
unerheblich.  Ausserdem knnen sich grere Probleme dadurch ergeben,  da die 
rsrc_load()-Systemfunktion per malloc() Speicher anfordert.
  Aus  diesem  Grund  kann es in manchen Fllen sinnvoll  sein,  die  vom  RCS 
erzeugten  Datenstrukturen direkt in das C-Programm einzubinden,  so da  beim 
Programmstart  keine  extra Ressource-Datei mehr ntig ist.    Dies  kann  auf 
mehrere  Arten  erfolgen.  Das Original-RCS von DRI besitzt  die  Mglichkeit, 
auer  der normalen RSC-Datei eine Datei mit der Endung RSH zu  erzeugen,  die 
die  Ressource-Daten  als C-Source enthalten.  Diese Dateien  haben  aber  ein 
Problem:  die  erzeugten  Strukturen sind eine exakte 1:1-Umsetzung  der  RSC-
Datei,  wie  sie  auf Diskette vorliegt.  Um die Ressource-Daten  im  Programm 
benutzen zu knnen, mssen allerdings noch einige nderungen an den Strukturen 
erfolgen (Umwandlung von Index in die entsprechende Struktur in einen  richti-
gen  Zeiger - und das teilweise auch noch abhngig von Objekttyp  unterschied-
lich),  die normalerweise von der Betriebssystemroutine rsrc_load() beim Laden 
von Diskette automatisch durchgefhrt werden - diese Initialisierungen mssten 
von einer eigenen Routine durchgefhrt werden, die die Programmlnge erhht.
  Das Programm RSH2RSI geht einen anderen Weg:  Es liest eine vom RCS erzeugte 
RSH-Datei  und erzeugt wahlweise eine Datei mit der Endung '.C'  oder  '.RSI'. 
Diese  Dateien  enthalten  die  Ressource-Strukturen  inclusive  den   ntigen 
Initialisierungen der verschiedenen Pointer. Die Initialisierung wird also vom 
Compiler  bernommen  und mu nicht mehr durch eine eigene  Routine  erfolgen. 
Turbo-C  erzeugt  fr solche initialisierten,  globalen Strukturen  kein  Byte 
initialisierungs-Code  -  die  Relozierung  erfolgt  direkt  durch  den   TOS-
Programmlader.
Die einzige Initialisierung,  die das Programm noch vornehmen mu,  besteht im 
Anpassen der Ressourcedaten an die aktuelle Auflsung. Die dazu ntige Routine 
(6 Zeilen) wird vom Konverter auf Wunsch automatisch  erzeugt.
  ACHTUNG:  Wenn Ihr Ressourcefile Icons oder Images enthlt,  so mssen diese 
vor  der Benutzung auf dem Bildschirm erst ins gerteabhngige Format  konver-
tiert  werden  (VDI-Funktion vr_trnfm()).  Dies ist auch  bei  Verwendung  der 
Betriebssystemfunktion rsrc_load notwendig und wird deshalb hier nicht  weiter 
erwhnt (s. T.OREN: "Professional Gem, Part VI", sowie ST-Computer 10/1989, S. 
60/61). Auf einem normalen ST geht es zwar ohne, aber bei manchen Grafikkarten 
(oder TT) knnten die Icons etwas seltsam aussehen ...

Die beiden Dateien, die erzeugt werden knnen, unterscheiden sich wie folgt:
 - Die  '.RSI'-Datei  kann direkt per '#include "name.rsi"'  in  das  Programm 
   eingebunden werden.  Es sind keine extra Projektdateien  etc.  ntig.  Dies 
   bietet sich besonders bei kleinen Programmen an.
 - Die  '.C'-Datei  ist bis auf einen Unterschied mit der  '.RSI'-Datei  iden-
   tisch:  sie enthlt am Anfang zustzlich die Anweisung '#include  <aes.h>'. 
   Diese  Datei kann als extra Modul compiliert werden und wird dann zum  Rest 
   des Programms dazugelinkt. Dis bietet sich besonders bei Programmen an, die 
   aus mehreren Quelltexten erzeugt werden. Die Kompilierzeiten sind geringen, 
   da  nicht bei jedem Compilerlauf die Ressourcestrukturen mitbersetzt  wer-
   den. Die Ressourcedaten werden ber 'extern'-Deklarationen angesprochen. Im 
   Programm  selbst  sind bei der Umstellung von  '.C'  auf  '.RSI'-Ressourcen 
   keinerlei nderungen notwendig.

  Die nderungen,  die ntig sind,  um bestehende Programme auf  'eingebaute' 
Ressourcen umzustellen, sind gering.
  Da  bei  dieser Methode der Compiler die Initialisierung  von  Strings  etc. 
bernimmt,  mu man der Compileroption 'merge duplicate strings',  die gleiche 
Strings  auch  im Speicher auf eine  Adresse  legt,  besondere  Aufmerksamkeit 
widmen.  Bei Texten,  die nur angezeigt werden,  entstehen keine Probleme. Bei 
editierbaren  Textfeldern  mu  man aber darauf achten,  da man  im  RCS  fr 
'te_ptext'  (der String,  der beim Editieren verndert wird)  unterschiedliche 
Startwerte  fr verschiedene Strings eintrgt - sonst legt der Compiler  diese 
Strings zusammen,  was zu seltsamen Ergebnissen fhrt.  In schwierigen  Fllen 
kann diese Compileroption auch abgeschaltet werden - dann ist aber die  gerade 
bei  greren  Ressourcen  sprbare  Speicherplatzeinsparung  weg.  Es  sollte 
ausreichen, die Compileroption nur fr das Ressource-Modul auszuschalten.

  Die  beschriebene  Methode  der Ressourceinitialisierung  und  das  Programm 
RSC2RSI sind eventuell auch mit anderen Compilern als Turbo-C  anwendbar.  Das 
Programm setzt folgendes voraus:
 - die AES-includedatei des Compilers heit 'aes.h'
 - Die GEM-Strukturen (OBJECT, TEDINFO, ...) sind nach ANSI sauber deklariert, 
   das heit z.B.  fr den OBSPEC-Eintrag:  kein 'long' oder 'void*',  sondern    
   eine UNION, die alle mglichen Werte zult etc.

  Mit dem Programm erhalten Sie eine Beispiel-Ressource-Datei (editierbar  mit 
DRI  RCS V2.0) als RSC-file und in konvertierter Form sowie drei  Beispielpro-
gramme, die die drei Methoden demonstrieren, wie man Ressourcen anwenden kann:
 - EXAMPLE1.C  -  der  normale  weg  ber  das  Betriebssystem:   rsrc_load(),    
   rsrc_gaddr(), rsrc_free() etc.
 - EXAMPLE2.C - fest eingebaute Ressourcen per Include-Datei 'EXAMPLE.RSI'
 - EXAMPLE3.C  -  fest  eingebaute Ressourcen ber  ein  extra-Modul  fr  die 
   Ressourcen  (EXAMPLE.C).   Zu  diesem  Programm  gehrt  die   Projektdatei 
   EXAMPLE3.PRJ

PROGRAMMOPTIONEN
----------------
Nach dem Programmstart erscheint eine Dialogbox,  in der man folgende Wahlmg-
lichkeiten hat:
'->*.C'  /  '->*.RSI': Auswahl,  ob eine RSI- oder eine C-Datei erzeugt werden 
                       soll (s.o.).

'#defines part1'     : bernahme  des ersten #define-Blocks aus der  RSH-Datei 
                       (wird normalerweise nicht bentigt)
'#defines part2'     : dito fr den zweiten Block von #defines
'free strings'       : bernahme der 'free-strings' in die konvertierte Datei. 
                       Diese Strings gehren zu keinem bestimmten  Objektbaum, 
                       sondern enthalten Definitionen fr Alert-Boxen etc. 
'free images'        : bernahme von Images, die zu keinem Objektbaum gehren.
'rs_trindex[]'       : Erzeugen  der Tabelle rs_trindex[].  Diese enthlt  die 
                       Adressen der verschiedenen Objektbume.  Wenn das  Pro-
                       gramm  nur  einen  Objektbaum  bentigt,   kann   diese  
                       Tabelle entfallen.
'rs_imdope[]'        : Erzeugt die Tabelle rs_imdope[].  Keine  Ahnung,  wofr 
                       man die brauchen kann.
'include *.h'        : hngt  an die erzeugte Datei den Inhalt der  '.H'-Datei 
                       an,  die Definitionen von Objekt- und Baumnummern  ent-
                       hlt.  Bei der Verwendung der Option 'RSI' braucht  man 
                       dan im Programm kein extra '#include "xxx.h"' mehr.
'create rsrc_init()' : erzeugt  in der konvertierten Datei eine Funktion  void 
                       rsrc_init(void), die beim Programmstart EINMAL aufgeru-
                       fen  werden sollte und die die Anpassung ALLER  Objekte 
                       an  die aktuelle Bildschirmauflsung bernimmt  (Aufruf 
                       von rsrc_obfix()).

'Start'              : Startet die Konvertierung.  In der Dateiauswahlbox kann 
                       man dann die RSH-Quelldatei angeben.  ACHTUNG: wenn die 
                       angewhlte Quelldatei keine vom RCS erzeugte  RSH-Datei 
                       ist, kann sich das Programm eventuell aufhngen!
'Quit'               : Beendet das Programm.

Die Benutzung des Programms geschieht auf eigene Gefahr.  Ich bernehme  keine 
Haftung  fr  Schden  jeglicher Art,  die durch den Einsatz  oder  durch  die 
Nichtbenutzung  des  Programms entstehen.  Sollte das  Programme  noch  Fehler 
enthalten,  bin ich aber fr eine Beschreibung,  wie sich der Fehler  reprodu-
zieren lt, dankbar.

Das Programm darf fr den privaten Gebrauch beliebig kopiert  werden,  solange 
ALLE Dateien mitkopiert werden. Das Copyright bleibt aber beim Autor. Wenn Sie 
das  Programm fters verwenden,  sollten Sie mir einen  beliebigen  Geldbetrag 
zukommen lassen (5-10DM wren wohl angemessen).
Wenn Sie Fragen oder Probleme mit dem Programm haben, knnen Sie sich gerne an 
mich wenden:

Michael Schwingen
Kranichstrae 10
W-5042 Erftstadt
Germany

(Wenn Sie Disketten schicken: Bitte frankierten Rckumschlag beilegen)
email:
michaels%messua.informatik.rwth-aachen.de@unido.bitnet (auerhalb BRD)
michaels@messua.informatik.rwth-aachen.de (nur innerhalb BRD bitte)
PLEASE KEEP MAIL FROM OUTSIDE GERMANY SHORT - I HAVE TO PAY FOR INCOMING MAIL !




RSH2RSI - GEM ressource converter V1.2
--------------------------------------
GEM  offers the possibility to create screen dialogs,  menus  etc.  by  simply 
editing those elements using an RCS (Ressource Construction Set).
  While  this  makes it easy for the programmer do write  programs  with  nice 
menus,  dialog boxes etc.,  there is also a negative side:  every GEM  program 
needs an extra ressource file (name.RSC) which has to be loaded every time the 
program is executed.  This is painful if the program was not executed from the 
current  DOS path,  because in this case the ressource file can not be  found. 
When using accessories,  the need to load extra ressource files slows down the 
boot   process  substantially  and  can  cause  major  problems  because   the 
rsrc_load()  system  function  uses  malloc()  to  allocate  memory  for   the 
ressource.
  
  For  these  reasons,  it  may  be useful to  integrate  the  ressource  data 
structures  right  into the source,  thus eliminating the need  to  load  them 
separately.  This can be done by various methods.  The original RCS by DRI has 
the  possibility to create an extra file with the extension RSH when saving  a 
ressource.  This file contains the ressource data as c source  code.  However, 
the  structures in these files are a direct conversion of the RSC file  as  it 
can be found on disk.
  In order to use those structures in a program,  there are some things  which 
have to be changed: various offsets to other structures have to be replaced by 
real  pointers,  depending  on  the type of the object  which  is  just  being 
converted.  Usually,  these  nasty  things  are done  by  the  system  routine 
rsrc_load() when loading the ressource data from disk.  When including the RSH 
file, we would have to do this with an own convert routine which increases the 
length of the program.
  The  program  RSH2RSI uses another method:  it reads a RSH  file  which  was 
created by RCS and creates a new file with the extension '.RSI' or '.C'.  This 
new file contains all ressource structures with all pointers  initialized,  so 
the compiler will do the rest.  Turbo-C does not create a single byte of  code 
for initializing those structures - the pointers are there in the DATA-segment 
and are relocated by the TOS program loader.
  The  only thing we have to do at the beginning of our program is to  convert 
all object structures to the actual screen resolution.  RSH2RSI can  automati-
cally insert a 6-line routine which does this automatically.
  WARNING:  If your ressource file contains ICONs or IMAGEs,  these have to be 
converted  to  the  device specific format before using them  on  screen  (VDI 
function  vr_trnfm()).  This  has  to be done when using  the  system  routine 
rsrc_load(),  too  (!) and so i will not discuss it further as it  is  nothing 
special with build-in ressources.  (T.OREN:  "Professional Gem,  Part VI", ST-
Computer 10/1989,  pp.  60/61). When using a normal ST, your program will most 
probably  work without vr_trnfm,  but on some new graphic cards (or  TT),  the 
ICONs might look strange ...

The two files which can be created differ as follows:
 - The  '.RSI'-file can be used by including it via '#include  "name.rsi"'  in 
   the main program.  There is no need for extra project files etc..  This  is 
   useful for small programs.
 - The '.C'-Datei is exactly the same as the '.RSI'-file except one  line:  it 
   contains an extra '#include <aes.h>' line.  This file can be compiled as an 
   extra module and is then linked together with the rest of the program.  The 
   compile  process is speeded up because the ressource data is compiled  only 
   on demand. The ressource data is accessed via 'extern' declarations. In the 
   program  itself,  there are no differences between using 'RSI' or 'C'  type 
   ressources.

There  are  only  minor changes required to change existing  programs  to  use 
build-in ressources.

  As  the compiler initializes strings,  we have to watch out for  a  compiler 
option  called 'merge duplicate strings',  which enables the compiler  to  put 
identical  strings  at the same memory location.  If those  strings  are  only 
displayed,  there is no danger. If the string belongs to the 'te_ptext' string 
of  an  editable text field (this is the string which is actually  changed  by 
editing the field), we have to watch out because if this string is merged with 
other strings,  these strings would be modified unwanted. For this reason, you 
should  take  care  that  those strings have  different  initial  values  when 
creating them in RCS. 
  In  difficult cases,  it may help to switch this compiler option off  -  but 
this disables the compiler to save memory. It should be sufficient to turn off 
the option only for the ressource module.

  The  described  method for initializing ressources as well  as  the  program 
RSH2RSI may be useful with other compilers than  Turbo-C,  too.  However,  the 
following conditions should be true:
 - the GEM AES include file of that compiler is called 'aes.h'
 - the GEM structures (OBJECT,  TEDINFO,  ...) are defined ANSI-like:  correct 
   pointers instead of 'long's, a UNION to define OBSPEC etc.

  Together with the program,  you get an example ressource file (which can  be 
edited  using DRI RCS V2.0) in the original RSC form as well as the  converted 
files. There are three example programs which demonstrate the possibilities to 
use ressources:
 - EXAMPLE1.C - the  normal  way  by using the GEM functions  to  handle  disk 
   ressources: rsrc_load(), rsrc_gaddr(), rsrc_free() etc.
 - EXAMPLE2.C - build-in ressources by using an include file ('EXAMPLE.RSI')
 - EXAMPLE3.C - build-in ressources by using an extra module 'example.c' which 
   contains  the  ressource  data.   This  program  needs  the  project   file 
   EXAMPLE3.PRJ to compile.

program options
---------------
After  starting  the  program,  a dialog box is  displayed  which  offers  the 
following options:
'->*.C'  /  '->*.RSI': Choose  if you want to create a RSI- or a  C-file  (see 
                       above)

'#defines part1'     : Take the first block of #define from the RSH file. This 
                       is usually not needed. 
'#defines part2'     : The same for the second block of #defines.
'free strings'       : Convert the 'free-strings'.  These are strings which do 
                       not belong to a certain object tree.  They contain data 
                       for alert boxes etc. 
'free images'        : Convert Images which do not belong to a special  object 
                       tree.
'rs_trindex[]'       : Create the rs_trindex[] table.  This table contains the 
                       addresses  of all object trees.  If your  program  uses 
                       only one object tree, this table can be omitted.
'rs_imdope[]'        : Converts the rs_imdope[]. I absolutely do not know what 
                       this table is good for.
'include *.h'        : This  option  attaches  the contents  of  the  *.h-file 
                       (which contains definitions of object and tree numbers) 
                       to the end of the converted ressource file.  When using 
                       the  RSI  output option,  thus eliminates the  need  to 
                       #include it in your program.
'create rsrc_init()' : In the converted file,  a function void rsrc_init(void) 
                       is  created  which  should be  called  ONCE  after  the 
                       program is started.  This function adapts ALL object to 
                       the current screen resolution by calling rsrc_obfix().

'Start'              : Starts  the  conversion.   A  GEM  fileselect  box   is 
                       displayed to select the RSH source  file.  WARNING:  if 
                       the  selected file is not a RSH file which was  created 
                       by RCS, the program might hang!
'Quit'               : Quits the program.

The  use  of this program is entirely at your own risk.  I am not  liable  for 
damages  resulting from the use or the inability to use this program.  If  you 
find bugs, please send me a note telling how the error can be reproduced.

The  program  may  be  freely copied for private use if  you  copy  ALL  FILES 
TOGETHER.  If you use the program frequently,  you should consider sending  me 
some money (5-10DM or equiv. in other currencies would be appropriate).

If you have any problems or questions, feel free to contact me:

Michael Schwingen
Kranichstrasse 10
W-5042 Erftstadt
Germany

(When sending disks: please enclose a self-addressed, stamped envelope)
email:
michaels%messua.informatik.rwth-aachen.de@unido.bitnet
(preferred from outside FRG)
michaels@messua.informatik.rwth-aachen.de 
(only if above does not work or if mailing from inside FRG)
PLEASE KEEP MAIL FROM OUTSIDE GERMANY SHORT - I HAVE TO PAY FOR INCOMING MAIL !
-------------------------------------------------------------------------------

