Dokumentation zu UTIL.A geschrieben von Holger Weets Letzte Žnderung: 03.04.92 Diese Bibliothek wurde mit und fuer SOZOBON-C entwickelt und ist Shareware, darf also zusammen mit dieser Dokumentation von jedem frei kopiert werden, muž allerdings bei regelm„žiger Benutzung durch Zu- sendung eines Betrages von 20,- DM erworben werden. Updates: - gem_name() sollte jetzt fehlerfrei arbeiten - get_key() wartet jetzt auf einen Tastendruck - get_key(), xinkey(), sinkey(), chrdel() &strdel() wurden in Assmebler neu implementiert - in der Dokumentation fehlte die Funktion input() - exinkey(), dtostr(), strtod() berarbeitet Die Funktionen: void chrdel(char *string, int pos) string -- String, aus dem ein Zeichen entfernt werden soll pos -- Index des zu loeschenden Zeichens Mit dieser Funktion k”nnen einzelne Zeichen aus einem String entfernt werden. void chrins(char *string, int pos, char c) string -- String, in den ein Zeichen eingefuegt werden soll pos -- Index der Einfuege-Position c -- einzufuegendes Zeichen Mit dieser Funktion koennen einzelne Zeichen in strings eingefuegt werden. void strins(char *src, char *ins) src -- String, in den eingefgt werden soll ins -- String, der eingefgt werden soll Mit dieser Funktion kann ein String am Anfang eines anderen eingefgt werden. Eine Positionsangabe als Parameter ist deshalb nicht n”tig, trotzdem k”nnen hiermit die Strings an beliebige Stelle in andere Strings eingefgt werden, zu diesem Zweck ist die Funktion wie folgt aufzurufen: strins(string + offset, ins_string); void strdel(char *str, int anz) str -- String aus dem gel”scht werden soll anz -- soviele Zeichen werden vom Anfang des Strings gel”scht Mit dieser Funktion k”nnen Zeichen am Anfang eines Strings gel”scht werden. Um Zeichen aus der String-Mitte zu l”schen, kann die Funktion wie folgt aufgerufen werden: strdel(string + offset, Anzahl) void get_key(char *c, int *scan) c -- ASCII-Code des Zeichens scan -- modifizierter Scancode des Zeichens Mit dieser Routine k”nnen einzelne Zeichen von der Tastatur eingelesen werden. Zurckgeliefert wird - sofern vorhanden - der ASCII-Code des Zeichens, sowie sein wie folgt modifizierter Scancode: Aužer dem eigentlichen Scancode wird noch mittels Kbshift() der Status der Kontroll-Tasten geholt. Dieser wird zun„chst so modifiziert, das in ihm maximal noch die Bits fr Shift- links/rechts, Control- und Alternate- Taste gesetzt sein k”nnen. Danach wird noch eine einheitliche Darstellung beider Shift-Tasten vorgenommen, und die so entstandenen Bits 'hinten' an den Scancode angeh„ngt (Bits 8-11). Der Fall, das Bit 2 in der Systemvariablen 'conterm' gesetzt ist, wird ebenfalls behandelt. (Siehe dazu im Profibuch unter conterm). get_key() wartet, bis eine Taste gedrckt wurde. void inkey(char *c, int *scan) Diese Funktion wartet auf einen Tastendruck, d.h. die Kontrolle wird erst dann wieder an die aufrufende Routine zurckgegeben, wenn tat- s„chlich eine Taste gedrcket wurde und somit ein definiertes Ergebnis zurck-geliefert werden kann. Die zurckgegebenen Werte sind der ASCII-Code der gedrckten Taste und ihr Scan-Code. char ainkey() Diese Funktion liest - sofern vorhanden - ein Zeichen aus dem Tastatur- puffer und liefert dessen ASCII-Code zurck. Falls kein Zeichen vorhanden war, wird 0 zurckgegeben. int sinkey() Diese Funktion liest - sofern vorhanden - ein Zeichen aus dem Tastatur- puffer und liefert dessen Scan-Code zurck. Falls kein Zeichen vorhanden war, wird 0 zurckgegeben. int xinkey() Diese Funktion liest - sofern vorhanden - ein Zeichen aus dem Tastatur- puffer und liefert einen Wert zurck, welcher sich zusammensetzt aus dem Scancode der gedrckten Taste (Bits 0-7) und dem Status der Kontrolltasten (Bits 9-15). Dadurch ist es m”glich, alle Tasten- kombinationen zu unterscheiden (selbst ob die Taste mit der linken oder der rechten Shift-Taste gedrckt wurde). Falls kein Zeichen vorhanden war, wird 0 zurckgegeben. int exinkey() Diese Funktion liest - sofern vorhanden - ein Zeichen aus dem Tastatur- puffer und liefert einen Wert zurck, welcher sich zusammensetzt aus dem Scancode der gedrckten Taste (Bits 0-7) und dem Status der Kontrolltasten (Bits 9-15). Der Unterschied zu xinkey() (siehe oben) besteht darin, daž keine Unterscheidung zwischen linker und rechter Shift-Taste gemacht wird, insbesondere muž diese Unterscheidung nicht mehr im eigenen Programm implementiert werden. Ich habe diese Funktion deshalb geschrieben, weil die beschriebene Tasten-Unterscheidung wohl nie gebraucht werden wird und bei der Implementierung beispielsweise eines Editors sogar l„stig ist. Falls kein Zeichen im Tastatur-Puffer vorhanden war, wird 0 zurckgegeben. int input(int anzahl, char *set, char *buf, int flag) Komfortabler Zeileneditor. Dabei sind - anz -- Gr”že des Eingabebereiches (max. 80) - set -- die erlaubten Zeichen; ist leer, dann sind alle Zeichen erlaubt - buf -- Die eingegebene Zeile; kann am Anfang einen Defaultstring enthalten, der editiert werden kann - flag -- Eingabe bei unbekanntem Zeichen abbrechen ? Rckgabewert ist 0, falls mit Return/Enter abgbrochen wurde. Falls gesetzt ist, dann wird als Return-Wert der Scancode der Taste zurck- gegeben, die zur Beendigung der Eingabe gefhrt hat, oder 0, falls dies Return/Enter war. Folgende Tasten werden interpretiert: - Cursor rechts/links - Backspace - Delete - Esc (l”scht die Eingabezeile) unsigned int strtod(char *str) str -- hier steht das Datum drin Diese Funktion wandelt einen String-Inhalt in das Datum im Dos-Format um. Der String muž dabei folgendes Format haben: "TT.MM.JJJJ", Tag und Monat mssen zweistellig vorliegen und Jahr vierstellig. Das verwendete Trennzeichen (im Beispiel der Punkt) ist beliebig w„hlbar, nur einstellig muž es sein. unsigned int strtot(char *str) str -- hier steht die Uhrzeit drin Diese Funktion wandelt einen String-Inhalt in die Uhrzeit im Dos-Format um. Der String muž dabei folgendes Format haben: "SS:MM", Stunden und Minuten mssen zweistellig vorliegen. Das verwendete Trennzeichen (im Beispiel der Doppelpunkt) ist beliebig w„hlbar, nur einstellig muž es sein. void ttostr(char *str, unsigned int systime, char *delim) systime -- System-Zeit im Dos-Format str -- Ergebnis-String delim -- Trennzeichen Diese Funktion wandelt die System-Zeit in einen String um. Zurckgeliefert wird eine Zeichenkette der Form: wobei und zweistellig sind (fehlende Zeichen werden mit '0' aufgefllt), Beispiel: "01:13" void dtostr(char *str, unsigned int sysdate, char *delim) sysdate -- die Systemzeit im Dos-Format str -- der Ergenis-String delim -- das Trennzeichen Diese Funktion wandelt das System-Datum in einen String um. Zurckgeliefert wird eine Zeichenkette der Form wobei und zweistellig und vierstellig sind (fehlende Zeichen werden vorn mit '0' aufgefllt), Beispiel: "01.04.1990" unsigned long drv_free(int drive) drive -- Nummer des Laufwerks (0 = A: etc.) Diese Funktion liefert den freien Speicherplatz fr ein beliebiges Laufwerk. void zerlege(char *name, char *pfad) name -- Eingabe-Parameter, hier steht der zu zerlegende Pfad drin Ausgabe-Parameter, hier steht hinterher der Dateiname ohne Pfad drin pfad -- Ausgabe-Parameter, hier steht hinterher der Pfad ohne den Dateinamen drin Diese Funktion zerlegt einen Zugriffspfad in Pfad und Namen, wobei Ein- und Ausgabe-Parameter ist und pfad nur Ausgabe-Parameter. int copy(char *src, char *dest) src -- vollst„ndiger Name der Quelldatei dest -- vollst„ndiger Name der Zieldatei Diese Funktion kopiert die Datei nach . Beide Namen mssen vollst„ndig angegeben sein. Beispiel: copy("A:\TEST.C", "C:\") GEHT NICHT copy("A:\TEST.C", "C:\TEST.D") kopiert die Datei TEST.C von Drive A: unter dem Namen TEST.D auf Laufwerk C: Rckgabe-Wert ist entweder 0, dann hat alles geklappt, oder aber eine GEMDOS-Fehlernummer, dann ist etwas schiefgegangen. Das Kopieren der Dateien grožer Dateien geht um so schneller, je mehr Speicherplatz vorhanden ist. Die Routine kopiert n„mlich so viele Bytes wie m”glich auf einmal ('wie m”glich' = gesamter Speicherplatz - 8K). void chsuf(char *dest, char *src, char *ext) dest -- hier kommt der neue Name rein src -- hier steht der Datei-Name ext -- neue Extension (Namens-Endung) der Datei Diese Funktion „ndert die Extension des Dateinamens in und liefert das Ergebnis in zurck. Beispiel : 'chsuf(neu, "A:\TEST.C", "PRG")' liefert 'A:\TEST.PRG' in void gem_name(char *dest, char *src, int flag) Diese Funktion formatiert einen im TOS-Format vorliegenden Dateinamen in GEM-Format. Dabei ist TOS-Format z.B. 'TEST.C' also sozusagen unformatiert und GEM-Format ist dann 'TEST C', falls der String in ein formatiertes Textfeld einer Dialogbox eingetragen werden soll (flag != 0 setzen), oder 'TEST C', falls er z.B. in ein Directory-Fenster soll (flag = 0 setzen). In der Variablen steht das Ergebnis, die Variable wird nicht ver„ndert. void tos_name(char *dest, char *src) Diese Funktion ist das Gegenstck zu gem_name(), sie wandelt Datei- namen, welche im GEM-Format vorliegen, in TOS-Format um. In der Variablen steht das Ergebnis, die Variable wird nicht ver„ndert. Diese Funktion ist immer dann praktisch, wenn Dateinamen in Verbindung mit Fenstern oder Dialogboxen verwendet werden. Beispiel: 'TEST C' wird zu 'TEST.C' int wild(char *test, char *pattern) Diese Funktion implementiert einen Pattern-Matching-Alogorithmus, wie er z.B. unter UNIX blich ist. Erlaubt sind die Wildcards - * - pažt auf JEDE Zeichenkette (insbesondere auch den '.'), funktioniert somit NICHT, wie vom TOS gewohnt. - ? - pažt auf JEDES einzelne Zeichen (insbesondere auch den '.'), funktioniert somit ebenfalls NICHT, wie vom TOS gewohnt - [] - erzeugt eine Menge von Zeichen, die an der aktuellen Stelle erlaubt sind '[abc]*' pažt auf 'axxx', 'bxyz', 'cabs' aber nicht auf 'xabc' -! - wenn das erste Zeichen in der eckigen Klammer ein '!' ist, so passen alle Zeichen, die NICHT in der Menge sind '[!abc]*' pažt auf 'def', aber nicht auf 'axy' -\ - maskiert die Sonderzeichen (\! am Anfang einer Menge meint das '!' selbst, \] meint nicht das Ende der Menge, sondern das Zeichen ']' \nnn wird in das Zeichen umgewandelt, fuer das die OKTAL-Zahl nnn steht (\033 meint Escape (dezimal 27) ) Diese Routine ist NICHT von mir, sondern wurde von Fred Fish unter UNIX und AmigaDos implementiert. Ich habe sie lediglich im Hinblick auf Portierung durchgesehen und dann i.w. bernommen. char *xfgets(char *buffer, int len, FILE *file) Diese Funktion fhrt im wesentlichen die Arbeit von fgets() aus. Nachdem der Buffer eingelesen wurde, wird jedoch im Gegensatz zu fgets() das Zeilen-Ende-Zeichen noch entfernt. ES WIRD NICHT GEPRšFT, OB TATSŽCHLICH EINS VORHANDEN IST ! deshalb ist diese Fuktion nur verwendbar, wenn eine ganze Zeile Text eingelesen werden soll.