GeoRun Library

1. Starten und Beenden von anderen Applikationen
2. Fernsteuern anderer Applikationen

Die GeoRun Library erlaubt dem R-BASIC Programmierer mit anderem GEOS-Applikationen zu kommunizieren. Das können sowohl R-Apps (compilerte R-BASIC Programme) als auch andere GEOS-Applikationen, wie z.B. GeoWrite, sein. Dabei kann bei Bedarf eine Datendatei übergeben werden.

Um die GeoRun Library verwenden zu können, müssen Sie sie includen:

Include "GeoRun"

^

1. Starten und Beenden von anderen Applikationen

GeoRunStartApplication Übergibt eine Datei an eine Applikation, deren GeodeToken Sie kennen. Bei Bedarf wird die Applikation gestartet.
GeoRunOpenFile Öffnet eine Datendatei, wobei die zugehörige Applikation aus dem Typ der Datei ermittelt wird.
GeoRunFindDosApp Ermittelt die zu einer DOS-Datei gehörende GEOS Applikation.
GeoRunTestRunning Prüft, ob eine bestimmte GEOS-Applikation bereits läuft.
GeoRunCloseAppliaktion Schließt eine laufende GEOS-Applikation.

GeoRunStartApplication

GeoRunStartApplication öffnet eine GEOS-Applikation und übergibt ihr eine Datendatei. Sie müssen selbst darauf achten, dass der Typ der Datei zur Applikation passt.

Sie können GeoRunStartApplication auch verwenden, um einer bereits laufenden Applikation eine (weitere) Datei zu übergeben.

Deklaration:

FUNCTION GeoRunStartApplication(appToken as GeodeToken, dataFile as String(32)) as WORD

Parameter:

appToken: GeodeToken der zu öffnenden Applikation.: Wenn die Applikation noch nicht läuft, wird sie gestartet. Dazu muss sie sich im World-Verzeichnis, einem seiner Unterverzeichnisse oder im SysAppl-Verzeichnis befinden.
dataFile: Name der zu übergebenden Datei.: Die Datei muss sich im aktuellen Ordner befinden und zur zu startenden Applikation passen. Ein Leerstring ist zulässig.

Return: Null oder Fehlercode.

Die globale Variable fileError wird gesetzt. Siehe unten.

Hinweise:

Ist das zugehörige Programm ein R-BASIC Programm, so wird die Datei dem OnStartup-Handler übergeben, falls das Programm neu gestartet werden müsste. Läuft es bereits, so wird die Datei dem OnConnection-Handler übergeben.
GeoRunStartApplication kann (wie jede Function in R-BASIC) auch wie eine SUB benutzt werden. Siehe Beispiel.

Details zum Fehlercode

GeoRunStartApplication und GeoRunOpenFile liefern Null, wenn die Applikation erfolgreich gestartet werden konnte bzw. bereits läuft. Andernfalls liefern die Routinen einen Fehlercode. Außerdem setzen diese Routinen die globale Variable fileError (Null oder Fehlercode).

Positive Fehlercodes und Fehlercodes im Bereich von -50 bist Null sind R-BASIC "Standard"-Codes. Sie können die Routine ErrorText$() verwenden, um eine Beschreibung des Fehlers zu erhalten. Typische Fehlermeldungen sind:

ERROR_FILE_NOT_FOUND: Die Datendatei existiert nicht im aktuellen Ordner
ERROR_ACCESS_DENIED: Der Zugriff wurde verweigert. Dieser Fehler tritt auch auf, wenn Sie einen Ordner statt einer Datei angeben.

Die Fehlercode -51 und -52 sind library-interne Fehler. Sie sind folgendermaßen definiert:

CONST LIB_ERROR_OPENING_APP      = -51
  ! Die Applikation konnte nicht gestartet werden, meist weil
  ! keine Applikation mit dem übergebenen Token gefunden wurde.
CONST LIB_ERROR_NO_DOS_APP       = -52
  ! Es wurde keine passende DOS-Applikation in der INI gefunden.
  ! Auch ein *.* - Eintrag existiert nicht.

Beispiel: Öffnen von GeoWrite mit einer Datei im Document-Ordner

DIM AppToken AS GeodeToken

  AppToken.tokenchars = "WP00"
  AppToken.manufid = 0
  SetStandardPath(SP_DOCUMENT)
  
  GeoRunStartApplication(appToken, "Karte Danke")

GeoRunOpenFile

GeoRunOpenFile übergibt eine Datei an die zugehörige Applikation, damit diese sie öffnen kann. Die Datei muss sich im aktuellen Ordner befinden. Für VM-Dateien (z.B. GeoWrite-Dokumente) und GEOS Daten-Dateien wird die zugehörige Applikation aus dem Dateityp ermittelt (Creator-Token), für DOS-Dateien wird die zugehörige Applikation aus der GEOS.INI ( [fileManager] : filenameTokens) gelesen.

Deklaration:

FUNCTION GeoRunOpenFile(dataFile as String(32)) as WORD

Parameter:

dataFile: Name der zu öffnenden Datei.: Die Datei muss sich im aktuellen Ordner befinden. Die zugehörige Applikation wird automatisch ermittelt.

Return: Null oder Fehlercode.

Die globale Variable fileError wird gesetzt. Siehe auch: GeoRunStartApplication.

Hinweise:

Ist das zugehörige Programm ein R-BASIC Programm, so wird die Datei dem OnStartup-Handler übergeben, falls das Programm neu gestartet werden müsste. Läuft es bereits, so wird die Datei dem OnConnection-Handler übergeben.
GeoRunOpenFile kann (wie jede Function in R-BASIC) auch wie eine SUB benutzt werden.
Wenn Sie nicht wollen, dass bei einer DOS-Datei, für die keine explizite Zuweisung in der GEOS.INI existiert, die Default-Zurdnung "*.*" verwendet wird, benutzen Sie GeoRunFindDosApp, um zu prüfen, ob eine explizite Zuweisung in der GEOS.INI existiert.
GeoRunOpenFile kann auch eine Applikation starten, wenn sie sich im aktuellen Ordner befindet.

Beispiel: Öffnen einer Grafik-Datei im Document-Ordner

  SetStandardPath(SP_DOCUMENT)
  GeoRunOpenFile("MANJUL.GIF")

GeoRunFindDosApp

GeoRunFindDosApp durchsucht die GEOS.INI nach der zu einer DOS-Datei gehörenden Applikation und liefert das zugehörige GeodeToken.

Deklaration:

FUNCTION GeoRunFindDosApp(dataFile as String(32), findStar as Integer) as GeodeToken

Parameter:

dataFile: Kompletter Name der DOS-Datei.

Wenn Sie nur die Dateierweiterung kennen, übergeben Sie hier einen fiktiven Namen, z.B. "X.EXT" oder "*.EXT".

Übergeben Sie niemals nur die Dateierweiterung! Das wird als Dateiname ohne Erweiterung interpretiert!

findStar: TRUE oder FALSE

TRUE: Falls keine explizite Zuordnung gefunden wurde, wird das Token der "*.*" Zuordnung zurückgeliefert - falls eine solche Zuordnung existiert.
FALSE: Falls keine explizite Zuordnung gefunden wurde wird immer eine Null-Token zurückgeliefert. Die Zuordnung zu *.* wird ignoriert.

Return: GeodeToken der zugehörigen Applikation, oder ein Null-Token, wenn keine zugehörige Applikation gefunden wurde.

Beispiel: Finden des Standard-Browsers (HTML-Betrachter)

DIM AppToken AS GeodeToken
  appToken = GeoRunFindDosApp("*.HTM", FALSE)
  MsgBox appToken.tokenChars + "," + Str$(appToken.manufID)

Hinweis:

Um zu prüfen, ob ein Null-Token zurückgeliefert wurde, können Sie die Funktion NullStruct() verwenden.

DIM appToken as GeodeToken
  appToken = GeoRunFindDosApp("MYFILE.DTF", FALSE)
  IF appToken = NullStruct() THEN ....

GeoRunTestRunning

GeoRunTestRunning prüft, ob eine bestimmte Applikation bereits läuft, oder nicht.

Deklaration:

FUNCTION GeoRunTestRunning(token as GeodeToken) as Integer
Parameter:: token: GeodeToken der fraglichen Applikation.
Return: TRUE: Die Applikation läuft bereits.: FALSE: Die Applikation läuft noch nicht.
Warnung! GeoRunTestRunning schließt eine eventuell bestehende Connection zum getesteten Programm.: Diese Warnung ist nur relevant, wenn Sie GeoRunOpenConnection (siehe unten) verwenden.

Beispiel: Prüfen, ob GeoWrite schon läuft

DIM x
DIM AppToken AS GeodeToken

  AppToken.tokenchars = "WP00"
  AppToken.manufid = 0
  x = GeoRunTestRunning(AppToken)
  IF x THEN MsgBox "GeoWrite läuft schon"

GeoRunCloseAppliaction

GeoRunCloseApplication schließt eine laufende GEOS-Applikation. Genauer: sie wird aufgefordert sich zu schließen, genau so, als ob der Nutzer "Beenden" aus dem Datei-Menü gewählt hätte.

Deklaration:

FUNCTION GeoRunCloseApplication(token as GeodeToken) as Integer
Parameter:: token: GeodeToken der zu schließenden Applikation.
Return: TRUE: Die Applikation lief und wurde aufgefordert, sich zu beenden.: FALSE: Die Applikation wurde nicht gefunden (lief nicht).
Warnung! GeoRunCloseApplication schließt eine eventuell bestehende Connection zum Programm.: Diese Warnung ist nur relevant, wenn Sie GeoRunOpenConnection (siehe unten) verwenden.

Beispiel: GeoDraw schließen

DIM AppToken AS GeodeToken

  AppToken.tokenchars = "DP00"
  AppToken.manufid = 0  
  GeoRunCloseApplication(AppToken)

^

2. Fernsteuern anderer Applikationen

Mit den hier bereitgestellten Routinen können Sie eine Verbindung ("Connection") zu anderen GEOS-Programmen herstellen und diesen Befehle senden. Das können R-BASIC Programme oder andere GEOS-Applikationen (z.B. GeoWrite) sein.

GeoRunOpenConnection etabliert eine Connection zu einem anderen Programm. Es liefert einen Word-Wert (ConnectionToken), der von den anderen Routinen benötigt wird.
GeoRunSendMessage sendet einen Text und einen Word-Wert an den OnConnection-Handler eines verbundenen R-BASIC Programms.
GeoRunSendMessageBack sendet einen Text und einen Word-Wert an den OnConnection-Handler des Programms, dass die Verbindung hergestellt hat.
GeoRunSendKbdEvent simuliert einen Tastendruck für das verbundene Programm.
GeoRunCloseConnection schließt eine Verbindung zu einem anderen Programm wieder.

Während die Connection aktiv ist, können Sie mit GeoRunStartApplication oder GeoRunOpenFile (siehe vorn) eine Datendatei an das verbundene Programm senden.

GeoRunOpenConnection

GeoRunOpenConnection etabliert eine Connection zu einem anderen Programm. Dieses Programm wird als Server bezeichnet, während das aktuelle Programm (dass GeoRunOpenConnection aufgerufen hat) der Client ist. Wenn der Server noch nicht läuft, wird er gestartet. Während die Connection besteht, lässt sich der Server nicht beenden.

GeoRunOpenConnection liefert einen Word-Wert (ConnectionToken), der von den anderen Routinen benötigt wird.

Deklaration:

FUNCTION GeoRunOpenConnection(token as GeodeToken, data$ as String(32)) as Integer
Parameter:: token: GeodeToken des Servers.
data$: Name einer Datendatei aus dem aktuellen Ordner. Ein Leerstring (keine Datei) ist zulässig.
Return: ConnectionToken für die Verbindung.
Warnung! Wenden Sie weder GeoRunCloseApplication noch GeoRunTestRunning auf den Server an, solange die Connection besteht!: Diese Routinen schließen die bestehende Verbindung!
GeoRunStartApplication und GeoRunOpenFile hingegen können Sie gefahrlos verwenden.

Hinweise:

Falls der Server schon läuft ruft GeoRunOpenConnection den OnConnection-Handler des Servers auf, andernfalls den OnStartup-Handler.
Beachten Sie, dass das Öffnen einer Applikation und/oder das Laden eines Dokuments einen Moment dauern kann.
Falls Sie in dieser Situation direkt nach GeoRunOpenConnection einen Befehl senden, kann folgendes passieren:
GeoRunSendMessage: der OnConnection-Handler wird vor dem OnStartup-Handler (gerufen von GeoRunOpenConnection) ausgeführt.
GeoRunSendKbdEvent: der Tastendruck könnte ignoriert werden.

Beispiel: siehe GeoRunSendMessage und GeoRunSendKbdEvent

GeoRunSendMessage

GeoRunSendMessage sendet eine Information an den OnConnection-Handler des Servers. Sie besteht aus einem Text mit bis zu 250 Zeichen, der im Parameter dataFile$ an den Handler übergeben wird und einem Word-Wert, der im Parameter flags an den Handler übergeben wird. Es ist Aufgabe des Servers, die Informationen korrekt zu interpretieren.

GeoRunSendMessage setzt voraus, dass der Server ein R-BASIC Programm ist, dass mit R-BASIC 1.0 oder höher compiliert wurde.

Deklaration:

SUB GeoRunSendMessage(cTok as Word, data$ as String(250), flags as Word)
Parameter: cTok: ConnectionToken, geliefert von GeoRunOpenConnection
data$: beliebiger Text. Wird als Parameter dataFile$ an den OnConnection-Handler übergeben.
flags: beliebiger Word-Wert. Wird als Parameter flags an den OnConnection-Handler übergeben.

Hinweise:

Falls Sie mit GeoRunSendMessage eine den Namen einer Datendatei an den OnConnection-Handler übergeben wollen, sollten Sie den kompletten Pfad zu Datei übergeben. Einfacher ist die Verwendung von GeoRunStartApplication oder GeoRunOpenFile für diesen Zweck.
Falls Sie sowohl Datendateien als auch andere Kommandos an den Server senden wollen, können Sie Ihre Kommandos mit einem Zeichen beginnen, das nicht Teil eines Dateinamens sein kann, z.B. mit einem Sternchen *. Damit kann der OnConnection-Handler beides sicher unterscheiden. Das der Library beiliegende Beispiel macht davon Gebrauch.

Beispiel: Wir stellen eine Verbindung zu einem anderen Programm (dem Server) her und senden ihm das ConnectionToken. Der Server muss die Message in seinem OnConnection-Handler korrekt interpretieren. Der Code stammt aus dem der Library beiliegende Beispiel.

DIM AppToken AS GeodeToken
DIM globalCTok

  AppToken.tokenchars = "BOOK"   ' Muss zum Server passen
  AppToken.manufid = 5

  ' "*1" sagt dem Server, dass der 3. Parameter das 
  ' ConnectionToken ist
  globalCTok = GeoRunOpenConnection(AppToken, "")
  GeoRunSendMessage(globalCTok, "*1", globalCTok)

GeoRunSendMessageBack

GeoRunSendMessageBack kann vom Server aus gerufen werden und sendet eine Information an den OnConnection-Handler des Clients. Das benötigte ConnectionToken muss dem Server vorher mit GeoRunSendMessage übermittelt worden sein.

Es ist Aufgabe des Clients, die gesendete Informationen korrekt zu interpretieren.

Deklaration:

SUB GeoRunSendMessageBack(cTok as Word, data$ as String(250), flags as Word)
Parameter: cTok: ConnectionToken, geliefert von GeoRunOpenConnection
data$: beliebiger Text. Wird als Parameter dataFile$ an den OnConnection-Handler übergeben.
flags: beliebiger Word-Wert. Wird als Parameter flags an den OnConnection-Handler übergeben.

GeoRunSendKbdEvent

GeoRunSendKbdEvent simuliert einen Tastendruck für den Server. Der Tastendruck wird an das Application-Objekt übergeben und geht von dort direkt an das aktuell "aktive" Objekt.

Die Parameter sind die gleichen, wie bei der Methode KbdEventWithScancode. Dort, in den Kapiteln 14.2 und 14.3 des Handbuchs "Spezielle Themen" (Vol. 3), finden Sie eine ausführliche Beschreibung der Bedeutung der einzelnen Parameter.

GeoRunSendKbdEvent kann mit allen GEOS-Applikationen verwendet werden. Bitte beachten Sie die Hinweise unten.

Deklaration:

SUB GeoRunSendKbdEvent(cTok as Word, character as Word, kexState as Word, keyFlags as Word, scanCode as Word)
Parameter:: cTok: ConnectionToken, geliefert von GeoRunOpenConnection
character: ASCII-Code oder erweiterter ASCII-Code der Taste. Tipp: In der Library "KeyCodes" finden Sie symbolische Konstanten für die erweiterten ASCII-Codes.
keyState: Information, welche Status- oder Steuertasten aktuell gedrückt sind, z.B. KS_LSHIFT für die linke Shift-Taste.
keyFlags: Information, ob der Nutzer die Taste gerade gedrückt hat, sie gedrückt hält oder gerade losgelassen hat, z.B. KF_FIRST_PRESS
scanCode: Der Scancode der gedrückten Taste. Dieser Wert kann Null sein, es sei denn, Sie wollen ein Tastenkürzel wie "Strg-P" aktivieren.

Hinweise:

Im Allgemeinen ist es ausreichend, das "FIRST_PRESS" Event zu senden.
Menüpunkte, die über eine "Shortcut" Kombination wie Strg-P oder Shift-F4 angesprochen werden, können Sie mit GeoRunSendKbdEvent aktivieren.
Menüs oder Menüpunkte, die über die normale Tastaturnavigation, z.B. Alt-d, angesprochen werden, können Sie mit GeoRunSendKbdEvent nicht aktivieren.

Beispiel: Wir stellen eine Verbindung zu GeoWrite her und senden das Wort "Hallo" an das aktuelle Dokument. Dann öffnen wir den Drucken-Dialog (Strg-P). Für diesen Zweck benötigen wir den Scancode des Buchstaben P. Am Ende des Kapitels 14.3 im Handbuch "Spezielle Themen" finden wir dafür den Wert 25.

DIM cTok
DIM AppToken AS GeodeToken

  AppToken.tokenchars = "WP00"
  AppToken.manufid = 0

  cTok = GeoRunOpenConnection(AppToken, "")

  GeoRunSendKbdEvent(cTok, Asc("H"), 0, KF_FIRST_PRESS, 0)
  GeoRunSendKbdEvent(cTok, Asc("a"), 0, KF_FIRST_PRESS, 0)
  GeoRunSendKbdEvent(cTok, Asc("l"), 0, KF_FIRST_PRESS, 0)
  GeoRunSendKbdEvent(cTok, Asc("l"), 0, KF_FIRST_PRESS, 0)
  GeoRunSendKbdEvent(cTok, Asc("o"), 0, KF_FIRST_PRESS, 0)

  GeoRunSendKbdEvent(cTok, Asc("p"), KS_LCTRL, KF_FIRST_PRESS, 25)

  GeoRunCloseConnection(cTok)

GeoRunCloseConnection

GeoRunCloseConnection schließt eine mit GeoRunOpenConnection hergestellte Verbindung.

Deklaration

SUB GeoRunCloseConnection(cTok as Word)
Parameter:: cTok: ConnectionToken, geliefert von GeoRunOpenConnection

^

Weiter...