This page is also available in

Dokumentation

Dokumentationen nedan ingår i BeeBase-distributionen och finns även tillgänglig i PDF.

17. ARexx-gränssnitt

ARexx-gränssnittet är endast tillgängligt i BeeBase-versionen för Amiga.

ARexx är ett standardgränssnitt för Amiga-program för att möjliggöra åtkomst till funktioner och data från andra program. BeeBase tillhandahåller en sådan ARexx-port med en liten men väldefinierad uppsättning kommandon som gör det möjligt för ett externt program att praktiskt taget beräkna allt som ett BeeBase-program kan beräkna. Dessutom implementerar BeeBase ARexx-gränssnitt en transaktions- mekanism liknande andra relationella databaser.

Exempel på ARexx-skript för BeeBase finns i katalogen `rexx'.

17.1 Portnamn

Portnamnet för BeeBase ARexx-porten är `BeeBase.n' där n är en räknare som börjar med 1. Vanligtvis, om du startar BeeBase endast en gång, är portnamnet `BeeBase.1'.

Du behöver portnamnet i ARexx address-satsen innan du anropar något av BeeBase ARexx-kommandon. Följande program- fragment visar hur man kontrollerar förekomsten av en BeeBase ARexx-port, startar BeeBase om det behövs, och adresserar porten.

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

Se även exempel på ARexx-skript `address.rexx'.

17.2 Kommandosyntax

Efter att ha adresserat BeeBase ARexx-porten kan du anropa vilken som helst av BeeBase ARexx-kommandon. Syntaxen är densamma som för de flesta andra implementeringar:

cmd [arg1 ...]

där cmd är ett av kommandona som beskrivs längre ned i detta kapitel, och arg1 ... är valfria argument till kommandot.

Eftersom ARexx-tolken utvärderar kommandoraden innan den skickar den till BeeBase, är det ibland användbart att citera några eller alla av argumenten. Det rekommenderas att använda enkla citattecken (') runt argument som inte ska utvärderas ytterligare av ARexx-tolken. På detta sätt kan du fortfarande placera dubbla citattecken ("), t.ex. för strängkonstanter, i argumenten. Dessutom kan du integrera värdet av ARexx-variabler genom att avcitera dem. Här är ett exempel som använder BeeBase eval-kommando.

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

Se även Eval.

17.3 Returkoder

Efter att ha anropat ett av BeeBase ARexx-kommandon uppdateras flera ARexx-variabler med resultatet av kommandot. För att läsa alla resultat av ett kommando bör du aktivera ARexx-resultatoptionen genom att lägga till följande rad i början av ditt ARexx-skript.

options results

Det finns 3 ARexx-variabler som kan ställas in av BeeBase ARexx-gränssnittet: rc, results, och lasterror. Variabeln rc ställs alltid in och återspeglar framgången eller misslyckandet av ett kommando. Om ett kommando var framgångsrikt innehåller results det faktiska resultatet av kommandot, medan i fallet med ett misslyckat kommando kan lasterror innehålla ytterligare information som beskriver felet.

För variabeln rc finns följande returkoder:

Returkod  Betydelse

   0         Framgång. Variabeln result innehåller det faktiska resultatet.
  -1         Implementationsfel. Bör aldrig inträffa.
  -2         Slut på minne.
  -3         Okänt ARexx-kommando.
  -4         Syntaxfel.
 -10         Annat fel. Felbeskrivning kan hittas i lasterror.
 -11         Internt fel. Bör aldrig inträffa.
 -12         Kompileringsfel (endast för compile-kommandot).

Observera att endast för rc <= -10 innehåller variabeln lasterror en giltig felbeskrivning. I framtiden kan fler felkoder läggas till för att möjliggöra en mer detaljerad felhantering.

Här är ett typiskt kodfragment som visar hur man undersöker resultatet av ett BeeBase ARexx-kommando.

eval handle 'select * from Accounts' 
if (rc == 0) then
    say result
else if (rc == -1) then
    say "Implementationsfel"	
else if (rc == -2) then
    say "Slut på minne"	
else if (rc == -3) then
    say "Okänt kommando"	
else if (rc == -4) then
    say "Kommandosyntaxfel"	
else if (rc <= -10) then
    say lasterror
else
    say "Fel: " rc

17.4 Quit

Kommandot quit får BeeBase att avslutas. Se även MUI-dokumentationen.

17.5 Hide

Kommandot hide ikonifierar alla öppna BeeBase-fönster. Se även MUI-dokumentationen.

17.6 Show

Kommandot show deikonifierar BeeBase och öppnar fönstren igen. Se även MUI-dokumentationen.

17.7 Info

Kommandot info ger information om titel, författare, upphovsrätt, beskrivning, version, bas och skärm för en MUI-applikation.

Kommando          Värde av result

info title        Applikationens titel
info author       Applikationens författare
info copyright    Upphovsrättsmeddelande
info description  Kort beskrivning   
info version      Versionsträng
info base         Namn på ARexx-port
info screen       Namn på publik skärm

Se även MUI-dokumentationen.

17.8 Help

Kommandot help skriver en fil som innehåller alla tillgängliga ARexx-kommandon för en MUI-applikation.

help filnamn

ARexx-kommandon listas med hjälp av AmigaDos kommandoradssyntax. Se MUI-dokumentationen för mer information och din AmigaDos- manual för kommandoradssyntax.

17.9 Compile

Kommandot compile kompilerar en extern programkällfil.

compile källa [update]

Kommandot kompilerar den externa programkällan för projektet vars externa källfilnamn pekar på samma fil som källa. Vid framgång returnerar kommandot 0 och, om update har angetts, skriver om den externa källfilen. Uppdatering av källfilen möjliggör att snyggt formatera BeeBase-nyckelord. Ett framgångsrikt kompilerat program används sedan som projektets program och används när man kör utlösarfunktioner.

Om kompileringen misslyckas, returneras en felkod -12 och lasterror sätts till en sträng som innehåller 4 rader:

• Den första raden innehåller namnet på filen där felet inträffade.

• Den andra raden innehåller felradnumret som börjar med 1.

• Den tredje raden innehåller felkolumnen som börjar med 1.

• Den fjärde raden beskriver felet i läsbar text.

Observera att ett projekt måste ha öppnats redan innan du skickar compile-kommandot för att kompilera dess externa källa. Om inget projekt vars externa källfil pekar på källa hittas, returneras en felkod <= -10 (men annorlunda än -12) och lasterror sätts.

17.10 Connect

Kommandot connect öppnar kommunikationen till ett BeeBase-projekt.

connect projektnamn [GUI]

Kommandot kontrollerar först om projektet som anges av projektnamn redan har öppnats och laddar det om det behövs. Ett projekt öppnas endast en gång och flera anslutningar till samma projekt delar åtkomsten till databasen. Därefter genereras ett unikt kommunikationshandtag. Ett kommunikationshandtag är ett heltalsvärde som inte är lika med noll. Om nyckelordet GUI har lagts till på kommandoraden öppnas också det grafiska användargränssnittet för BeeBase-projektet. Annars genereras inget grafiskt användargränssnitt vilket möjliggör att bearbeta BeeBase ARexx-kommandon i bakgrunden utan direkt användarinteraktion.

Vid framgång, returnerar kommandot 0 och sätter result till värdet av handtaget.

Exempel: `connect "BeeBase:Demos/Movies.bbs"' upprättar en anslutning till exempel filmdatabasen.

Se även Disconnect, Connections, Return codes.

17.11 Disconnect

Kommandot disconnect stänger en befintlig anslutning.

disconnect handtag

Stänger databasanslutningen som anges i handtag. Om detta var den enda anslutningen till projektet som handtag refererar till och det inte finns något grafiskt användargränssnitt för projektet, då stängs projektet och tas bort från minnet. Annars förblir projektet öppet.

Exempel: `disconnect 1' stänger anslutningen med handtagsvärdet 1.

Se även Connect, Connections, Return codes.

17.12 Connections

För att ta reda på befintliga anslutningar, använd kommandot connections.

connections

Vid framgång returnerar connections 0 och sätter result till en läsbar sträng där varje rad visar en anslutning bestående av handtagsvärde och projektnamn.

Exempel: variabeln result efter ett anrop till connections skulle kunna se ut som följande:

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

Se även Connect, Disconnect, Return codes.

17.13 Eval

Huvudgränssnittet för BeeBase ARexx-port för att hämta och uppdatera data är genom eval-kommandot.

eval handtag lisp-cmd

Kommandot eval tolkar det givna kommandot lisp-cmd (skrivet i BeeBase lisp-språk) på projektet som anges av handtag. Ett handtag kan erhållas genom kommandot connect. Kommandot lisp-cmd kan vara vilket uttryck som helst i BeeBase programmeringsspråk. Valfritt kan de yttersta parenteserna runt uttrycket utelämnas. Det rekommenderas att omge lisp-cmd med enkla citattecken som beskrivs i Command syntax.

Om det lyckas, returnerar eval 0 och sätter result till en sträng- representation av returvärdet för lisp-cmd. Sträng- representationen görs på ett sätt som fortfarande tillåter att ta reda på vilken typ av data som returneras, t.ex. strängar omges av dubbla citattecken och listor omges av parenteser med objekt separerade av mellanslag eller nyradstecken. Om du vill säkerställa ett visst format, använd din egen formatering inom det angivna lisp-kommandot.

Om du gjorde ändringar i databasen inom eval-kommandot och inte startade en transaktion först (se Transaction) görs ändringarna automatiskt permanenta (auto-commit). Annars (du startade en transaktion innan du anropade eval) hålls ändringarna i minnet tills ett commit- kommando gör dem permanenta eller ett rollback-kommando ångrar ändringarna.

Exempel:

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	    

Utdata från ovanstående exempel skulle kunna se ut så här:

( ( "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" ) )

Se även Connect, Command syntax, Return codes, Transaction, Commit, exempel på ARexx-skript `movies.rexx'.

17.14 Transaction

BeeBase ARexx-port tillåter att göra transaktioner på en databas. En transaktion är en uppsättning kommandon till en databas (som tillåter ändringar av data i databasen) som antingen utförs och görs permanent fullständigt (commit) eller dras tillbaka vid någon punkt inom transaktionen (rollback). En transaktion kan startas genom att utfärda följande kommando:

transaction handtag

där handtag refererar till ett projekt som erhållits genom connect- kommandot (se Connect).

Efter att ha utfärdat ett transaction-kommando kan du lägga till så många eval-kommandon som du vill utan att faktiskt ändra databasen. Vid någon tidpunkt måste du dock bestämma om du vill göra ändringarna permanenta (se Commit) eller gå tillbaka till tillståndet innan du utfärdade transaction-kommandot (se Rollback).

Efter att ha utfärdat ett transaction-kommando, görs åtkomst till motsvarande projekt exklusivt för det angivna handtaget. Således blockeras andra program som försöker få åtkomst till databasen, inklusive användaren som kommer åt BeeBase via dess grafiska användargränssnitt (eller fördröjs i fallet med en annan ARexx-anslutning) tills den exklusiva åtkomsten släpps genom att anropa kommandot commit eller rollback.

Vanligtvis returnerar kommandot transaction 0. Om en annan ARexx-anslutning får exklusiv åtkomst till samma projekt som handtag refererar till, blockeras anropet tills den andra anslutningen avslutas genom att bekräfta eller återställa databasen.

Se även Eval, Commit, Rollback, Return codes.

17.15 Commit

Kommandot commit används i slutet av en transaktion för att göra ändringar permanenta.

commit handtag

Kommandot commit avslutar en transaktion (se Transaction) genom att spara projektet som argumentet handtag refererar till. Vid framgång returnerar commit 0. Om du inte startade en transaktion innan du anropade commit eller om något annat fel inträffar returneras ett värde som inte är lika med 0.

Se även Rollback, Transaction, Return codes.

17.16 Rollback

För att avbryta ändringar gjorda i en transaktion, använd kommandot rollback.

rollback handtag

Alla ändringar gjorda i projektet som handtag refererar till sedan början av den aktuella transaktionen (se Transaction) dras tillbaka och tillståndet för projektet före transaktionen återställs. Om det lyckas returnerar rollback 0.

Se även Commit, Transaction, Return codes.

This document was generated on September, 6 2025 using texi2html