This page is also available in

Handbuch

Die folgende Dokumentation ist Bestandteil der BeeBase-Distribution und gibt es auch als PDF.

17. ARexx Schnittstelle

Die ARexx-Schnittstelle ist nur in der BeeBase-Version für Amiga verfügbar.

ARexx ist eine Standardschnittstelle für Amiga-Software, um Zugriff auf Funktionen und Daten eines Programms nach außen für ein anderes Programm bereitzustellen. BeeBase bietet eine solche ARexx-Schnittstelle mit einem kleinen aber wohldefinierten Befehlssatz an, welcher es externer Software erlaubt, den vollen Zugriff über BeeBase zu erhalten. Weiterhin stellt die ARexx-Schnittstelle von BeeBase einen Transaktionsmechanismus ähnlich zu anderen relationalen Datenbanken bereit.

Beispiel-ARexx-Befehlsdateien für BeeBase findet man im Verzeichnis `rexx'.

17.1 Portname

Der Portname des BeeBase ARexx-Ports lautet `BeeBase.n' wobei n ein Zähler beginnend mit 1 ist. Normalerweise, d.h. wenn Sie BeeBase nur einmal starten, lautet der Portname `BeeBase.1'.

Sie benötigen den Portnamen für den ARexx-Befehl address, welcher aufgerufen werden muss, bevor irgendein ARexx-Befehl von BeeBase aufgerufen wird. Das folgende Programmfragment zeigt wie man das Vorhandensein des BeeBase ARexx-Ports feststellen kann, BeeBase ggf. startet und dann den Port adressiert.

if ~show(ports, BeeBase.1) then
do
    address command 'run <nil: >nil: BeeBase:BeeBase -n'
    address command 'waitforport BeeBase.1'
end
    
address BeeBase.1                  

Siehe auch Beispiel-ARexx-Befehlsdatei `address.rexx'.

17.2 Befehlsaufbau

Nachdem der ARexx-Port von BeeBase adressiert wurde, stehen alle BeeBase ARexx-Befehle zur Verfügung. Der Aufbau der Befehle ist ähnlich wie der vieler anderer Implementierungen:

cmd [arg1 ...]

wobei cmd einer der Befehle in den folgenden Teilen dieses Kapitels ist und arg1 ... optionale Argumente für den Befehl sind.

Da der ARexx-Übersetzer Befehlszeilen auswertet bevor sie an BeeBase gesendet werden, ist es manchmal nützlich, einige oder alle Argumente durch Anführungszeichen zu schützen. Es wird empfohlen einfache Anführungszeichen (') hierfür zu verwenden. Hierdurch können doppelte Anführungszeichen (") in den Argumenten, z.B. für Zeichenkettenkonstanten eingesetzt werden. Werden Argumente mit einfachen Anführungszeichen geschützt, so ist immer noch möglich, Werte von ARexx-Variablen mit in die Befehlszeile zu integrieren, indem um die ARexx-Variablen wiederum einzelne Anführungszeichen gesetzt werden. Hierzu ein Beispiel, welches den ARexx-Befehl eval verwendet.

search = ...
eval handle 'select Name from Person where (like Name "*'search'*")'

Siehe auch Eval.

17.3 Rückgabewerte

Nach dem Aufruf eines BeeBase ARexx-Befehls werden verschiedenen ARexx-Variablen mit dem Ergebnis des Aufrufs aktualisiert. Um das Lesen aller Resultate eines Befehls zu ermöglichen, sollten Sie die ARexx-Option results aktivieren. Dies erreicht man mit der folgenden Zeile am Anfang einer ARexx-Befehlsdatei.

options results

Es gibt 3 ARexx-Variablen, welche von der BeeBase-ARexx-Schnittstelle gesetzt werden können: rc, results und lasterror. Variable rc wird immer gesetzt und reflektiert den Erfolg oder Misserfolg eines Befehls. War ein Befehl erfolgreich, so enthält results das eigentliche Resultat des Befehls, wogegen im Falle eines Misserfolges, lasterror zusätzliche Information enthalten kann, die den Fehler genauer beschreibt.

Für die Variable rc existieren die folgenden Fehlerwerte:

Rückgabewert Bedeutung

   0         Erfolg.  Variable result enthält das Ergebnis.
  -1         Implementierungsfehler. Sollte nie auftreten.
  -2         Speicherplatzmangel.
  -3         Unbekannter ARexx-Befehl.
  -4         Syntax-Fehler
 -10         Anderer Fehler. Fehlerbeschreibung steht in lasterror.
 -11         Interner Fehler. Sollte nie auftreten.
 -12         Übersetzungsfehler (nur für compile-Befehl).

Man beachte, dass nur für rc <= -10 die Variable lasterror eine gültige Fehlerbeschreibung enthält. Weitere Rückgabewerte sind für zukünftige Versionen vorbehalten, um eine genauere Fehlerbehandlung zu ermöglichen.

Hier ist ein typisches Programmfragment, das zeigt wie man das Ergebnis eines ARexx-Befehls untersuchen kann.

eval handle 'select * from Accounts' 
if (rc == 0) then
    say result
else if (rc == -1) then
    say "Implementation error"	
else if (rc == -2) then
    say "Out of memory"	
else if (rc == -3) then
    say "Unknown command"	
else if (rc == -4) then
    say "Command syntax error"	
else if (rc <= -10) then
    say lasterror
else
    say "Error: " rc

17.4 Quit

Der Befehl quit beendet BeeBase. Siehe auch die MUI-Dokumentation.

17.5 Hide

Der Befehl hide schließt (ikonifiziert) alle offenen BeeBase-Fenster. Siehe auch die MUI-Dokumentation.

17.6 Show

Mit show werden alle zuvor geschlossenen (ikonifizierten) Fenster wieder geöffnet. Siehe auch die MUI-Dokumentation.

17.7 Info

Der Befehl info liefert Informationen über Titel, Autor, Copyright, Beschreibung, Version, ARexx-Port und Bildschirm einer MUI-Applikation.

Befehl            Wert von result

info title        Titel der Applikation
info author       Autor der Applikation
info copyright    Copyright-Nachricht
info description  Kurzbeschreibung
info version      Versionsnummer
info base         Name des ARexx-Ports
info screen       Name des Bildschirms

Siehe auch die MUI-Dokumentation.

17.8 Help

Der Befehl help gibt alle verfügbaren ARexx-Befehle einer MUI-Applikation in eine Datei aus.

help filename

Die ARexx-Befehle werden in der AmigaDos-Befehlssyntax ausgegeben. Siehe die MUI-Dokumentation für weitere Informationen und das AmigaDos-Handbuch für die Befehlssyntax.

17.9 Compile

Der compile-Befehl übersetzt eine externe Programmquelldatei.

compile source [update]

Der Befehl übersetzt die externe Programquelldatei des Projekts, dessen externe Programmquelldatei auf die gleiche Datei wie source zeigt. Bei erfolgreicher Übersetztung wird 0 zurückgegeben und, falls update angegeben wurde, die externe Quelldatei aktualisiert. Das Aktualisieren der Quelldatei erlaubt es die BeeBase-Schlüsselwörter zu "verschönern" (pretty print). Ein erfolgreich übersetztes Programm wird als Projektprogramm übernommen und bei Aufruf von Auslösefunktionen verwendet.

Schlägt die Übersetzung fehl, so wird der Fehlerwert -12 zurückgeliefert und die Variable lasterror auf eine 4 Zeilen lange Zeichenkette gesetzt:

• Die erste Zeile enthält den Dateinamen, in welcher der Fehler auftrat.
• Die zweite Zeile enthält die Fehlerzeile beginnend mit 1.
• Die dritte Zeile enthält die Fehlerspalte beginnend mit 1.
• Die vierte Zeile beschreibt den Fehler im Klartext.

Bitte beachten Sie, dass ein Projekt bereits geöffnet sein muss bevor der compile-Befehl zum Übersetzen seiner externen Programmquelle benutzt werden kann. Im Falle, dass kein Projekt, dessen externe Programmquelle mit source übereinstimmt, gefunden werden kann, wird ein Fehlerwert <= -10 (aber ungleich -12) zurückgegeben und lasterror entsprechend gesetzt.

17.10 Connect

Der connect-Befehl öffnet einen Kommunikationskanal zu einem BeeBase-Projekt.

connect project-name [GUI]

Der Befehl überprüft zunächst, ob das durch project-name angegebene Projekt bereits geöffnet wurde und lädt es gegebenenfalls. Ein Projekt wird immer nur einmal geöffnet und mehrfache Verbindungen zum gleichen Projekt teilen sich den Zugriff auf die Datenbank. Es wird ein eindeutiges Handle zur Kommunikation bestimmt. Das Kommunikations-Handle ist eine Ganzahl ungleich Null und wird später für den Zugriff auf die Datenbank benötigt. Falls das Schlüsselwort GUI der Kommandozeile angehängt wurde, so wird zusätzlich beim Öffnen des Projekts die graphische Benuzterschnittstelle des Projekts geöffnet. Andernfalls wird keine graphische Benutzerschnittstelle angezeigt und ARexx-Befehle werden im Hintergrund ohne direkte Benutzerinteraktion verarbeitet.

Falls das Öffnen des Projekts erfolgreich verlief, gibt der Befehl eine 0 zurück und setzt die ARexx-Variable result auf den Wert des Kommunikations-Handles.

Beispiel: `connect "BeeBase:Demos/Movies.bbs"' öffnet eine Verbindung zur Beispiel-Filmdatenbank.

Siehe auch Disconnect, Connections, Rückgabewerte.

17.11 Disconnect

Der disconnect-Befehl schließt eine bestehende Verbindung.

disconnect handle

Schließt die durch handle angegebene Datenbankverbindung. Falls es die einzige Verbindung zu diesem Projekt war und kein graphisches Benuzterinterface für das Projekt geöffnet wurde, so wird das Projekt geschlossen und aus dem Speicher entfernt. Andernfalls bleibt das Projekt geöffnet.

Beispiel: `disconnect 1' schließt die Verbindung zum Datenbank-Projekt mit Handle-Wert 1.

Siehe auch Connect, Connections, Rückgabewerte.

17.12 Connections

Um herauszufinden, welche Verbindungen zu Projekten bestehen, dient der Befehl connections.

connections

Falls erfolgreich, gibt connections den Wert 0 zurück und setzt die ARexx-Variable result auf eine lesbare Zeichenkette, bei der jede Zeile eine Verbindung bestehend aus Handle-Wert und Projektnamen enthält.

Beispiel: die Variable result könnte nach Ausführen des connections-Befehls wie folgt aussehen:

   3 BeeBase:Demos/Accounts.bbs
   5 BeeBase:Demos/Movies.bbs
   6 BeeBase:Demos/Movies.bbs
   7 BeeBase:Demos/Movies.bbs

Siehe auch Connect, Disconnect, Rückgabewerte.

17.13 Eval

Der wichtigste Befehl des BeeBase-ARexx-Ports um Daten abzufragen und zu aktualisiern, ist der eval-Befehl.

eval handle lisp-cmd

Der eval-Befehl wertet die angegebene Anweisung lisp-cmd (welche in der BeeBase-Lisp-Sprache geschrieben sein muss) in dem durch handle angegebene Projekt aus. Ein Kommunikationskanal handle kann durch Aufrufen des connect-Befehls erhalten werden. Die Anweisung lisp-cmd kann ein beliebiger Ausdruck der BeeBase-Programmiersprache sein. Optional können die äußersten Klammern um den Ausdruck herum weggelassen werden. Es wird empfohlen, lisp-cmp mit einfachen Anführungszeichen wie in Befehlsaufbau. beschrieben zu versehen.

Falls die Anweisung erfolgreich ausgeführt werden konnte, so gibt eval eine 0 zurück und setzt die ARexx-Variable result auf eine Zeichenkettenrepräsentation des Ergebniswertes von lisp-cmd. Die Zeichenkette repräsentiert dabei das Ergebnis in einer solchen Weise, dass es möglich ist, die Art der zurückgegebenen Daten herauszufinden. Beispielsweise werden Zeichenketten mit doppelten Anführungszeichen und Listen mit Klammern versehen, wobei die Listenelemente durch Leerzeichen und Zeilenvorschübe getrennt werden. Falls Sie ein bestimmtes Zeichenketten-Format erzwingen möchten, so bietet es sich an, diese Format selber innerhalb der Lisp-Anweisung zu erzeugen.

Falls eine Veränderung des Projekts innerhalb des eval-Befehls vorgenommen wurde und keine Transaktion (siehe Transaction) gestartet wurde, so werden die Änderungen automatisch gespeichert (auto commit). Andernfalls, d.h. es wurde eine Transaktion gestartet, werden die Änderungen im Speicher gehalten, bis ein commit-Befehl alle Änderungen speichert, oder ein rollback-Befehl alle Änderungen zurücknimmt.

Beispiel:

options results
address BeeBase.1
connect "BeeBase:Demos/Movie.bbs"
if rc = 0 then
do
    handle = result
    eval handle 'select Title, Director from Movies'
end
if rc = 0 then
    say result	    

Die Ausgabe dieses Beispielprogramms könnte wie folgt aussehen:

( ( "Title" "Director" )
  ( "Batman" "Tim Burton" )
  ( "Batman Returns" "Tim Burton" )
  ( "Speechless" "Ron Underwood" )
  ( "Tequila Sunrise" "Robert Towne" )
  ( "Mad Max" "George Miller (II)" )
  ( "Braveheart" "Mel Gibson" )
  ( "2010" "Peter Hyams" ) )

Siehe auch Connect, Befehlsaufbau, Rückgabewerte, Transaction, Commit, Beispiel-ARexx-Befehlsdatei `movies.rexx'.

17.14 Transaction

Der ARexx-Port von BeeBase erlaubt es Transaktionen auf einer Datenbank auszufüheren. Eine Transaktion ist eine Menge von auf einer Datenbank operierender Befehlen, welche möglicherweise die Datenbank verändern und die entweder alle komplett ausgeführt werden mit einem abschließenden Speichern aller Änderungen (commit), oder zu einem beliebigen Zeitpunkt innerhalb der Transaktion abgebrochen werden können (rollback). Eine Transaktion wird durch den folgenden Befehl gestartet:

transaction handle

wobei handle auf ein Projekt verweist, das zuvor mit dem connect-Befehl geöffnet wurde (siehe Connect).

Nach dem Ausführen eines transaction-Befehls können beliebig viele eval-Befehle folgen ohne dass die Datenbank tatsächlich verändert wird. Irgendwann jedoch müssen Sie entscheiden, ob die Änderungen gespeichert werden sollen (siehe Commit), oder ob zu dem Zustand vor Ausführen des transaction-Befehls zurückgekehrt werden soll (siehe Rollback).

Nach Ausführen des transaction-Befehls erhält das zugehörige Kommunikations-Handle einen exklusiven Zugriff auf das Projekt. Andere Programme, welche auf die Datenbank zugreifen wollen, inkl. der Benutzerschnittstelle, werden blockiert (bzw. verzögert im Falle einer ARexx-Verbindung), bis der exklusive Zugriff durch einen commit- oder rollback-Befehl wieder freigegeben wird.

Normalerweise gibt der transaction-Befehl den Wert 0 zurück. Falls ein anderes ARexx-Programm bereits exklusiven Zugriff zu dem Projekt hat, auf welches handle verweist, so wird die Ausführung blockiert bis die andere Verbindung den Zugriff wieder freigibt.

Siehe auch Eval, Commit, Rollback, Rückgabewerte.

17.15 Commit

Der commit-Befehl wird am Ende einer Transaktion aufgerufen, um alle getätigten Änderungen eines Projekts zu speichern.

commit handle

Der commit-Befehl beendet eine Transaktion (siehe Transaction) indem das Projekt, auf das handle verweist, gespeichert wird.

Falls erfolgreich gibt commit den Wert 0 zurück. Falls keine Transaktion gestartet wurde vor Ausführen von commit oder falls ein anderer Fehler auftritt, so wird ein Wert ungleich 0 zurückgegeben.

Siehe auch Rollback, Transaction, Rückgabewerte.

17.16 Rolback

Um alle Änderungen einer Transaktion zu verfwerfen, wird der rollback-Befehl verwendet.

rollback handle

Alle Änderungen, die an dem Projekt, auf welches handle verweist, seit dem Start der aktuellen Transaktion (siehe Transaction) vorgenommen wurden, werden verworfen und der Zustand des Projekts wird auf den Zustand wie vor Ausführen der Transaktion gebracht.

Falls erfolgreich so gibt rollback den Wert 0 zurück.

Siehe auch Commit, Transaction, Rückgabewerte.

Dieses Dokument wurde am 30. September 2024 mit texi2html generiert.