Dokumentation der phobos.library Version 1.29 vom 16.06.1991 geschrieben von DR. KRALLE/TIME-LIGHT 02271-97338 -------------------------------------------------------------- Die phobos.library ab Version 1.2 is Share-Ware. Die Nutzung ist kostenlos, sofern diese nicht in komerziellen Programmen verwendet wird. In diesem Fall muß eine Genehmigung beim Programmierer der Library oder des Mailboxprogrammes Phobos eingeholt werden. Die phobos.library ist für die Nutzung der Phobos-Schnittstelle programmiert worden, um relativ einfach die von Phobos gebotenen Features nutzen zu können. Sie stellt alle nötigen Routinen für eine Komunikation mit Phobos zur Verfügung. Die einzelnen Aufrufe können in jeder beliebigen Programmiersprache vorgenommen werden. Die phobos.library darf nur in Verbindung mit dieser Dokumentation sowie der beiliegenden Beispielprogramme weitergegeben werden. Auch wenn die Library Share-ware ist und keine Gebühr erhoben wird, unterliegt sie doch dem Copyright, deshalb bitte Abstand von jeglichen Manipulationen nehmen. Fairness muss sein... --------------------------------------------------------------------- WICHTIG ! WICHTIG ! WICHTIG ! WICHTIG ! WICHTIG ! WICHTIG ! WICHTIG ! --------------------------------------------------------------------- Die neue Phobosversion wird Multiuser fähig sein. Aus diesem Grund mußten einige Routinen der library angepasst werden, wodurch es durchaus sein kann, das bisherige über die Library programmierte Tools nicht mehr lauffähig sind. Doch in fast allen Fällen genügt eine kleine Änderung im Externen Programm. Der Aufruf der externen Programme hat sich ein wenig geändert. Als Parameter muß nun wieder $p als erstes Argument an das externe Programm übergeben werden (natürlich nur bei Programmen, die über die Library programmiert sind!). In $p wird in Zukunft der Userport übergeben, auf den der User angerufen hat, so das damit einwandfrei identifizierbar ist, auf welchen Port das Programm laufen soll. Wird dieser Parameter weggelassen oder ist außerhalb des Bereiches von 0 - 7, wird der Standardport Nummer 0 genommen. Also bitte nie den Parameter vergessen! Programme, die nicht über die Library programmiert sind, werden wohl in Zukunft nicht mehr im Multiuserbetrieb laufen, da diese fast immer das serial.device ansteuern und im Multiuserbetrieb natürlich eine Multiface-Karte installiert werden muß, deren Device zu 90% (außer Commodore Multiface-Karte) einen anderen Namen besitzen. Installation der Phobos-Library: -------------------------------- Die phobos.library wird in den LIBS-Ordner der Boot-Diskette kopiert. Damit ist die Installation auch schon vollkommen abgeschlossen (Puh, so ein Aufwand...). Beispiel Installation eines externen Porgrammes: ------------------------------------------------ Externe Programme, die über die Library laufen, müssen folgendermaßen installiert werden: In PhobosPref->Extern unter Name den gewünschten Namen eintragen, der nichts mit dem tatsächlichen Namen des Programms zu tun haben muß, sondern nur beim Aufruf Extern über die Box aufgelistet wird. Dann den entsprechenden Level einstellen und unter 1. Aufruf den kompletten Pfad mit Namen des Programms eintragen. Unbedingt wichtig ist ein RUN-Befehl vor dem Namen, aber KEIN! RUNBACK, sondern das normale RUN. Also sähe der Aufruf für z.B. 17+4 folgendermaßen aus, wenn sich dieses in der Directory OG auf Platte DH1: befindet: run dh1:og/17+4 $p RUN und $p bitte NIE vergessen... ------------------------------------------------------- HINWEIS FÜR PROGRAMMIERER ! HINWEIS FÜR PROGRAMMIERER ! ------------------------------------------------------- Die mit $p übergebene Portnummer wird als normales Argument an das externe Programm übergeben und ist ein Zeichen im ASCII-Code ('0' - '7') und kann folgendermaßen übernommen werden: C-Beispiel für die Auswertung von $p: ------------------------------------- main(int argc, char **argv[]) { struct PhobosBase *PhobosBase; long PortNum PortNum = atol(argv[1]); PhobosBase = (struct PhobosBase *) OpenLibrary("phobos.library",0L); if(!(Port = OpenPhobos(portnum))) goto PortFehler(); .. .. hier das eigentliche Programm .. ClosePhobos(Port); PortFehler: CloseLibrary(PhobosBase); exit(0); } Assembler-Beispiel: ------------------- OpenLibrary = -408 OpenPhobos = -30 ClosePhobos = -36 CloseLibrary = -414 Start: moveq #0,d0 move.b (a0),d0 sub.b #48,d0 move.l d0,PortNum move.l 4.w,a6 lea LibName(pc),a1 jsr OpenLibrary(a6) move.l d0,PhobosBase move.l PhobosBase,a6 move.l PortNum,d0 jsr OpenPhobos(a6) move.l d0,PhobosPort beq.s PortFehler .. .. hier das eigentliche Programm .. move.l PhobosBase,a6 move.l PhobosPort,a0 jsr ClosePhobos(a6) PortFehler: move.l 4.w,a6 move.l PhobosBase,a1 jsr CloseLibrary(a6) rts PhobosBase: dc.l 0 PhobosPort: dc.l 0 PortNum: dc.l 0 Und zu guter letzt noch in Pascal: ---------------------------------- Program Phobostest; {$incl 'phobos.lib' } Var PhobosPort:Ptr; PortNum:byte; Para:STRING; Begin OpenLib(PhobosBase,'phobos.library',0); Para:=ParameterStr; PortNum:=byte(Para[1])-48; PhobosPort:=OpenPhobos(PortNum); .. .. hier das restliche Programm .. ClosePhobos(PhobosPort); CloseLib(PhobosBase); End; Die Beschreibung der Library-Funktionen --------------------------------------- -------------------------------------------------------------------------- PhobosPort = OpenPhobos(long portnum) -30 D0 D0 OpenPhobos stellt die Verbindung zu Phobos her. Ist PhobosPort = 0, konnte die Verbindung nicht hergestellt werden. Bei korrekter Verbindung steht in PhobosPort die Adresse der Phobosschnittstelle. Als Parameter muß die Portnummer übergeben werden, die das externe Programme durch $p (siehe obiger Hinweis für Programmierer) erhalten hat. Dadurch beziehen sich nun alle Libraryfunktionen des externen Programms nur auf diesen Port, so daß ohne Probleme auf einen der anderen Ports weitere externe Programme gestartet werden können. -------------------------------------------------------------------------- ClosePhobos(PhobosPort) -36 A0 Die mit OpenPhobos hergestellte Verbindung wieder trennen. -------------------------------------------------------------------------- SerOut(long PhobosPort,APTR string) -42 A0 A1 Den Text, dessen Adresse string enthält, auf die Schnittstelle ausgeben. Beispiel: --------- SerOut(PhobosPort,"Hello, World!"); Der Text wird auf dem Bildschirm und auf die serielle Schnittstelle ausgegeben. -------------------------------------------------------------------------- BYTE c = ChSer(PhobosPort) -48 D0 A0 Zeichen von Schnittstelle holen Beispiel: --------- while(c = ChSer(PhobosPort) != 'j'); /* Auf taste j warten */ ChSer holt ein Zeichen von der Schnittstelle. Das Zeichen ist im ASCII-Code oder 0, wenn keins eingegeben wurde. Die Funktion kehrt sofort zurück. -------------------------------------------------------------------------- DelSome(long PhobosPort,long num) -54 A0 D0 Die in num angegebenen Anzahl Zeichen löschen (Backspace). Beispiel: --------- DelSome(PhobosPort,10); Ab der aktuellen Cursorposition werden 10 Zeichen rückwärts gelöscht. -------------------------------------------------------------------------- ModOut(long PhobosPort,APTR string) -60 A0 A1 Stringausgabe nur zum Modem Beispiel: --------- ModOut(PhobosPort,"Hello"); Der Text wird nur auf die serielle Schnittstelle ausgegeben. Auf dem Bildschirm wird nichts angezeigt. -------------------------------------------------------------------------- (UBYTE)c = ChMod(PhobosPort) -66 D0 A0 Zeichen vom Modem holen (nur Modem) Es wird ein Zeichen nur vom Modem geholt. Eine Tasteneingabe an der Console ist nicht möglich. Sonst verhält sich diese Funktion wie ChSer(). -------------------------------------------------------------------------- ModIn(long PhobosPort,APTR dest) -72 A0 A1 Zeichenkette vom Modem holen und an Adresse dest ablegen. Es wird eine Zeichenkette von der seriellen Schnittstelle gelesen und an einer angegebenen Adresse abgelegt. -------------------------------------------------------------------------- Print(long PhobosPort,APTR string) -78 A0 A1 String ohne Umlautwandlung auf Bildschirm ausgeben Beispiel: --------- Print(PhobosPort,"Test"); Der Text wird ohne Umlautwandlung direkt auf den Bildschirm ausgegeben. -------------------------------------------------------------------------- PrintIBM(long PhobosPort,APTR string) -84 A0 A1 String mit Umlautwandlung ausgeben. Der Text wird unter Zuhilfenahme einer Umlautwandlung auf den Bildschirm ausgegeben. Die serielle Schnittstelle bleibt dabei unberührt. Die Funktion Print() und PrintIBM() können benutzt werden, um dem Sysop eine Information zukommen zu lassen, die der User am Modem nicht sehen soll. -------------------------------------------------------------------------- GetKey(long PhobosPort,APTR buffer) -90 A0 A1 String eines Tastendrucks holen und in Buffer ablegen. Beispiel: --------- GetKey(PhobosPort,buffer); Hold den gesammten String eines Tastendruckes. Funktionstasten liefern zum Beispiel nicht nur 1 Zeichen, sondern eine Sequenz von Zeichen zurück. -------------------------------------------------------------------------- XonXoff(long PhobosPort,BOOL) -96 A0 D0 XonXoff ein- (BOOL = TRUE) oder ausschalten (BOOL = FALSE) -------------------------------------------------------------------------- OpenSer(long PhobosPort) -102 A0 Die serielle Schnittstelle öffnen -------------------------------------------------------------------------- CloseSer(long PhobosPort) -108 A0 Serielle Schnittstelle schließen -------------------------------------------------------------------------- ModemCommand(long PhobosPort,APTR string) -114 A0 A1 Die in string stehenden Modembefehle an das Modem senden Beispiel: --------- ModemCommand(PhobosPort,"ATDP...."); Führt das Wählkommando des Modems aus. Hiermit kann das Modem programmiert werden. Alle im String enthaltenen Zeichen werden als Modem-Kommando interpretiert und nicht über Telefonleitung gesendet. -------------------------------------------------------------------------- FileDownload(long PhobosPort,APTR name) -120 A0 A1 Das(die) File(s) in name downloaden Beispiel: --------- FileDownload(PhobosPort,"c:dir"); Die Datei C:Dir wird downgeloadet. -------------------------------------------------------------------------- FileUpload(long PhobosPort) -126 A0 File(s) uploaden. Die Files werden in die aktuelle Directory abgelegt. Durch ChangeDir() kann der Pfad vorher bestimmt werden. -------------------------------------------------------------------------- ShowStatus(long PhobosPort,APTR string) -132 A0 A1 Den in string enthaltenen Text in der Phobos-Statusanzeige ausgeben lassen. -------------------------------------------------------------------------- PhobosWindow(long PhobosPort,BOOL) -138 A0 D0 Phoboswindow öffnen (TRUE) oder schließen (FALSE) -------------------------------------------------------------------------- SerIn(long PhobosPort,anzahl,APTR string,APTR buffer) -144 A0 D0 A1 A2 Den in string enthaltenen Text ausgeben, dann maximal anzahl Zeichen lesen und nach buffer kopieren. Es werden solange Buchstaben gelesen, bis entweder Return gedrückt wurde oder die maximale Anzahl Zeichen erreicht wurde. -------------------------------------------------------------------------- SetEmulation(long PhobosPort,emulation) -150 A0 D0 Emulation des Users einstellen, Dabei kann emulation die Werte 0 (TTY), 1 (VT100) oder 2 (ANSI) annehmen. -------------------------------------------------------------------------- GetUserName(long PhobosPort,APTR buffer) -156 A0 A1 Usernamen holen und in buffer ablegen Es wird der Username des gerade aktiven Users geholt und in einen angegebenen Buffer kopiert. Das Format ist ein typischer C-String, also mit einem NULL-Byte als Abschluß. -------------------------------------------------------------------------- Level = GetLevel(long PhobosPort) -162 D0 A0 Den Userlevel des aktuellen Users holen -------------------------------------------------------------------------- con = Console(long PhobosPort) -168 D0 A0 Zustand des Logins abfragen. TRUE bedeutet Konsolen-Login und FALSE normaler Login. -------------------------------------------------------------------------- bool = WaitingLogin(long PhobosPort) -174 D0 A0 Abfragen, ob Mailbox im Wartezustand ist (TRUE), sonst FALSE -------------------------------------------------------------------------- PrintAt(long PhobosPort,long x, long y, APTR string) -180 A0 D0 D1 A1 Den Text, auf den string zeigt, an Bildschirmposition x,y ausgeben. Beispiel: --------- PrintAt(PhobosPort,10,12,"Hello!"); Gibt den Text 'Hello' an Cursorposition X-10 und Y-12 aus. -------------------------------------------------------------------------- bool = GetCarrier(long PhobosPort) -186 D0 A0 Zustand des Carriers abfragen. Carrier vorhanden = TRUE, sonst FALSE. -------------------------------------------------------------------------- ClrScreen(long PhobosPort) -192 A0 Löschen des Bildschirms. -------------------------------------------------------------------------- ChangeDir(long PhobosPort,APTR path) -198 A0 A1 Directory wechseln. Hiermit kann für einen Upload das Zieldirectory vorbestimmt werden. Path bestimmt dabei den Pfad. Identisch mit CLI-Kommando CD. -------------------------------------------------------------------------- SaveProtokoll(long PhobosPort) -204 A0 Phobos veranlassen, das Protokoll zu speichern. -------------------------------------------------------------------------- long Anzahl = SortNet(long PhobosPort) -210 D0 A0 Einsortieren der Netznachrichten in die entsprechenden Bretter. Anzahl enthält die Anzahl der tatsächlich einsortierten Nachrichten. -------------------------------------------------------------------------- long Nummer = GetUserNum(long PhobosPort) -216 D0 A0 Nummer des gerade aktiven Users holen -------------------------------------------------------------------------- void ReadUser(long PhobosPort,char *buffer, long UserNum) -222 A0 A1 D0 Gesamten Userdatensatz des User mit der Usernummer 'UserNum' holen und in den mit 'buffer' angegebenen Buffer kopieren. Die Usernummer kann mit der Funktion GetUserNum() geholt werden. -------------------------------------------------------------------------- void WriteUser(long PhobosPort,char *buffer, long UserNum) -228 A0 A1 D0 Gesammten Userdatensatz des User mit der Usernummer 'UserNum' speichern. Der mit GetUserNum() und ReadUser() in den Speicher geholten Datensatz des Aktiven Users kann nach einer Editierung mit dieser Funktion wieder zurückgeschrieben werden. -------------------------------------------------------------------------- result = AskResident(long PhobosPort) -234 D0 A0 Ermitteln, ob Programm resident im Speicher bleiben muß. Wenn der Rückgabewert 0 ist, muß sich das Programm beenden, ohne ClosePhobos aufzurufen, bei einem Wert != 0 muß dieses im Speicher bleiben, jedoch ohne nochmals OpenPhobos() aufrufen zu müssen. -------------------------------------------------------------------------- void TypeFile(long PhobosPort,APTR Filename) -240 A0 A1 Inhalt einer Datei ausgeben. TypeFile(PhobosPort,"s:startup-sequence"); Der Inhalt der Datei "startup-sequence" wird auf dem Bildschirm/Serielle ausgegeben. Mit dieser Funktion können also vorbereitete Texte schnell und einfach dem User angezeigt werden. -------------------------------------------------------------------------- void ReadSystemText(long PhobosPort,APTR Betreff) -246 A0 A1 Ausgabe eines Texten aus dem Brett Systemtexte auf den Bildschirm und der seriellen Schnittstelle. Als Betreff wird der Betreff angegeben, unter dem der Text im Brett Systemtexte abgelegt wurde, also wird zum Beispiel mit ReadSystemtext(PhobosPort,"BRETTINHALT"); Der Brettinhalt auf dem Bildschirm/Serielle ausgegeben. Mit dieser Funktion können also vorbereitete Texte schnell und einfach dem User angezeigt werden. -------------------------------------------------------------------------- void GetTime(long PhobosPort,APTR TimeBuf, APTR DateBuf) -252 A0 A1 A2 Ermitteln der aktuellen Uhrzeit und des aktuellen Datums. Beispiel: --------- GetTime(PhobosPort,Timebuf,Datebuf); In TimeBuf wird die aktuelle Uhrzeit im Format HH:MM:SS abgelegt. In DateBuf analog dazu das Datum im Format TT.MM.JJJJ -------------------------------------------------------------------------- Änderungen ---------- Version 1.1 vom 4.4.1991 ------------------------ Funktion "GetCarrier" und "PrintAt" integriert. Version 1.20 vom 6.4.1991 ------------------------- Funktion "Buffer", "SetBuffer", "DelBuffer", "InsertBuffer", "ClearBuffer", "AnsiClear" und "ChangeDir" integriert. Version 1.21 vom 7.4.1991 ------------------------- Funktion "SaveProtokoll" eingebaut. Version 1.22 vom 8.4.1991 ------------------------- Alle Funktionen optimiert, dadurch Library ca. 26% kleiner Version 1.23 vom 11.4.1991 -------------------------- Funktionen "GetFileSize", "ReadFile", "WriteFile", "KillFile" und "GetDosBase" integriert. Version 1.24 vom 28.4.1991 -------------------------- Funktion "Buffer", "SetBuffer", "DelBuffer", "InsertBuffer", "ClearBuffer", "ReadFile", "WriteFile" und "KillFile" entfernt. Funktion "GetNetParm" und "SortNet" eingebaut. Version 1.25 vom 30.5.1991 -------------------------- Kleiner Fehler in 'AnsiClear' behoben... Version 1.26 vom 7.6.1991 ------------------------- Entfällt Version 1.27 vom 12.6.1991 -------------------------- Library komplett in Assembler 'umgebastelt', dadurch 1. kleiner und 2. schneller geworden. Funktion GetUserNum(), ReadUser() und WriteUser() integriert. Funktion GetConfStr() in GetUserName() umbenannt. Funktion AnsiClear() in ClearScreen() umbenannt, da nun auch ein Löschen mittels VT100 Sequenz möglich ist. Funktionen Buffer(), SetBuffer() und InsertBuffer() vorläufig entfernt. Version 1.29 vom 16.06.1991 --------------------------- Funktion ClearScreen nochmals optimiert, nun ohne Parameter und in ClrScreen umbenannt. Neue Funktionen AskResident, TypeFile, ReadSysText und GetTime integriert. Library nun Multiuserfähig (Shared-Zugriff). In den bisher 2 1/2 Monaten, die die Library nun schon überdauert hat, hat sich vieles geändert. Alte Routinen sind entfernt worden und neue, optimalere dazugekommen. Das jetzige Gerüst wird in Zukunft beibehalten werden. Routinen werden keine mehr entfernt. Leider war anders nicht möglich zu erfahren, welche Routinen tatsächlich genutzt werden und welche überflüssig sind. Nun aber kann drauf los programmiert werden.