Andreas Papula R”merstraže 20 6200 Wiesbaden - Delkenheim Dokumentation zu EASYFSEL.C Version 1.27 Datum: 15.06.1992 Jeder, der auf dem ATARI ST/STE/TT Programme unter GEM schreibt, kam sicherlich schon einmal mit der Fileselectorbox und deren Programmierung in Berhrung. Schon die Funktion fsel_input ist nicht sonderlich leicht zu handhaben, da man erst die Rckgabeparameter auswerten und dann noch den vollst„ndigen Zugriffspfad zusammenbasteln muž [1]. Ab TOS 1.04 bzw. AES 1.4 gibt es dann noch die Version fsel_exinput, der zus„tzlich ein Titel bergeben wird. Man sollte also wenn m”glich diese Funktion benutzen, da man so den Anwender informieren kann, was er mit der Fileselectorbox ausw„hlen soll. Ein gutes Beispiel fr so einen Titel w„re z.B. "Bitte zu ”ffnende Datei ausw„hlen" oder so etwas „hnliches. Viele Programmierer wissen nun aber nicht, wie man in eigenen Programmen berprfen kann, ob fsel_exinput() berhaupt vorhanden ist und verwendet werden darf. Zus„tzlich zu dieser Problematik existiert noch der 'FSEL'-Cookie des alternativen Fileselectors "Selectric" (Shareware), der anzeigt, das unter jeder TOS- bzw. AES-Version fsel_exinput() vorhanden ist. Die Routinen... --------------- Ziel war es, eine kleine (aber feine) Routinensammlung zu entwickeln, die den Programmierer dabei untersttzt, die Fileselectorbox korrekt auf den Bildschirm zu bringen, inkl. Abfrage des 'FSEL'-Cookies. Nun ja, EASYFSEL.C stellt nun genau so eine Routinensammlung dar, die auch noch ber einige weitere Routinen, etwa Abfrage eines Cookies etc., verfgt. Doch zuerst m”chte ich die eigentliche Hauptroutine vorstellen, easy_fsel(). Der Funktionsprototyp (in der Datei EASYFSEL.H) lautet wie folgt: BOOLEAN easy_fsel(BYTE *pfad, BYTE *dateiname, BYTE *text); pfad ist dabei ein Zeiger auf einen String, der den Pfad enth„lt, mit dem fsel_input() bzw. fsel_exinput aufgerufen wird. Nach dem Ende der Funktion enth„lt pfad dann den vom Benutzer ausgew„hlten Pfad. Entsprechendes gilt fr dateiname. text ist der Titel, der bei fsel_exinput() erscheint. Der Rckgabewert der Funktion ist TRUE, wenn der Benutzer 'OK' ausgew„hlt hat und kein Fehler aufgetreten ist; FALSE, wenn 'ABBRUCH' ausgew„hlt wurde oder ein Fehler aufgetreten ist. Der neuen Datentyp BOOLEAN ist in EASYFSEL.H wie folgt definiert: typedef enum { FALSE, TRUE } BOOLEAN; Diesen Datentyp werden wird noch bei einigen Funktionen benutzen; er ist ganz ntzlich und Sie k”nnen ihn auch in eigenen Funktionen verwenden. easy_fsel() geht nun wie folgt vor: Zuerst werden (logisch) die benutzten Variablen deklariert, dann wird, wenn die AES-Version kleiner 0x0014 ist oder der 'FSEL'- Cookie nicht gefunden wurde, fsel_input aufgerufen, ansonsten fsel_exinput(). Die Parameter dieser beiden Funktionen m”chte ich hier erkl„ren, da diese fr die Benutzung der Routinensammlung unerheblich sind und zweitens in [1] sehr gut beschrieben sind. Die AES-Version steht im ersten Element des global-Feldes. Um an das global-Feld heran zu kommen, muž man folgende Deklaration in sein Programm aufnehmen: extern GEMPARBLK _GemParBlk; Damit wird eine Variable namens _GemParBlk vom Typ der Struktur GEMPARBLK deklariert. Diese Variable wird vom Startup-Code des PURE C-Compilers bereitgestellt. Achten Sie also darauf, wenn Sie einen anderen Startup-Code als einen der drei Originalen verwenden, daž die von Ihnen favorisierte Version sich in diesem Punkt genauso wie die Originale verh„lt! Auf global[] kann man dann wie folgt zugreifen: _GemParBlk.global() Das Suchen des Cookies bernimmt eine universell einsetzbare Routine namens get_cookie(), die besonders dazu geeignet ist, zu berprfen, ob ein Cookie vorhanden ist. Ich werde weiter unten noch genauer auf get_cookie() eingehen, doch zun„chst zurck zu easy_fsel(): Nachdem also fsel_input() oder fsel_exinput() aufgerufen worden sind, wird die Auswertung der Rckgabeparameter vorgenommen. Wenn der gedrckte Knopf 'Abbruch' ist oder ein fehler aufgetreten ist, wird FALSE zurckgegeben, ansonsten TRUE. Die aufrufende Funktion findet nun in pfad und dateiname die vom Benutzer gemachten Eingaben vor und kann diese nun per build_filename() zu einem gltigen Zugriffspfad zusammensetzen. build_filename() ist in EASYFSEL.H wie folgt deklariert: VOID build_filename(BYTE *dest, BYTE *pfad, BYTE *dateiname); šbergeben wird ein Zeiger auf einen String, der den kompletten Zugriffspfad nach Beendigung der Funktion enth„lt, ein Zeiger auf den Pfad und ein Zeiger auf den Dateinamen, aus denen der Zugriffspfad zusammengebastelt werden soll. Die Routine ist eigentlich selbsterkl„rend, so daž ich auf eine Beschreibung der Arbeitsweise hier verzichte. Des weiteren befindet sich noch die Funktion exist() in der Sammlung, mit der es m”glich ist, festzustellen, ob eine Datei existiert. der Prototyp sieht wie folgt aus: BOOLEAN exist(const BYTE *dateiname); Die Funktion t„tigt einen Aufruf der Funktion Fsfirst() und gibt, falls die Datei im Verzeichnis gefunden wurde, TRUE zurck, anderfalls FALSE. Gesucht wird dabei nach Dateien, die die Attribute 'READONLY', 'HIDDEN', 'SYSTEM' oder 'ARCHIVE' besitzen. Auch die Funktion get_akt_path() ist sicherlich hilfreich; sie liefert den aktuellen Pfad zusammen mit dem aktuellen Laufwerk, z. B. "D:\PC\SOURCEN\GEM". šbergeben wird ihr ein Zeiger auf einen String, in dem der Pfad dann stehen soll. Zurckgeliefert wird ein Zeiger auf eben diesen String. Es werden Aufrufe der PURE C - Spezialfunktionen getcurdir() und getdisk() get„tigt und aus deren Ergebnissen wird dann der aktuelle Pfad mit dem aktuellen Laufwerk zusammengebastelt. get_akt_path() ist in EASYFSEL.H wie folgt deklariert: BYTE *get_akt_path(BYTE *path); Cookie gesucht -------------- Nun kommen wir zur letzten Funktion, n„mlich get_cookie(), die ich weiter oben schon mal angesprochen habe. Ich m”chte hier allerdings nicht den prinziellen Aufbau des Cookiejar wiederholen, dieser ist z.B. in [1] oder [2] erl„utert. Zun„chst wird im Supervisor.Modus ein Zeiger auf den Cookiejar geholt. Wenn dort NULL steht, d.h. der Cookiejar leer ist, wird FALSE zurckgegeben. Andernfalls wird der Cookiejar solange durchlaufen, bist der gewnschte Cookie gefunden wird oder ein NULL-Zeiger vorkommt, d.h. der Cookiejar komplett durchlaufen wurde. Wenn der Cookie gefunden wurde, wird TRUE zurckgegeben und der Wert des Cookies der bergebenen Variable cookie_value zugewiesen. Wenn der Cookie nicht auffinderbar ist, wird FALSE zurckgegeben. Jetzt noch schnell der Prototyp von get_cookie(): BOOLEAN get_cookie(BYTE *cookie_name, LONG *cookie_value); Wenn Sie nun beispielsweise berprfen wollen, ob der 'VSCR'- Cookie (wird von BigScreen2, SciLab GmbH, gesetzt) vorhanden ist, k”nnen Sie also wie folgt vorgehen: ... long cookie_value = 0; if(get_cookie("VSRC", &cookie_value) == TRUE) { /* Cookie gefunden, Wert steht in cookie_value */ ... } else { ... } Was bleibt ? ------------ ... ist eine Routinensammlung, die man, sofern man Programme schreibt, die in irgendeiner Form mit Dateien zu tun haben, immer wieder verwenden kann und einem viel Gehirnschmalz erspart. Bei mir ist EASYFSEL.C nun schon einige Wochen im Einsatz und ich bin wirklich froh, daž ich mir die Mhe gemacht habe und mir eine wirklich universell einsetzbare Routinensammlung geschrieben habe. Das Modulkonzept von PURE C mit der guten Untersttzung durch den Projectmanager macht es einem wirklich leicht, modular aufgebaute Programme zu entwickeln und Module zu schreiben, die man immer wieder verwenden kann. Um in eigenen Programmen EASYFSEL.C verwenden zu k”nnen, mssen Sie EASYFSEL.H mittels #include in Ihre Programme einfgen und in die jeweilige Projectdatei EASYFSEL.C aufnehmen. Literaturhinweise: [1] Jankowski, Reschke, Rabich: ATARI Profibuch ST/STE/TT, Sybex 1991 [2] "STEE-Geb„ck - Das Cookie-Jar-Prinzip", ST-Computer 10/90, Seite 151-153