This page is also available in

Documentation

La documentation ci-dessous fait partie de la distribution de BeeBase. Elle est également disponible sous forme de PDF.

17. Interface ARexx

L'interface ARexx n'existe que pour la version Amiga de BeeBase.

ARexx est une interface standard pour des programmes Amiga qui permet d'accéder aux fonctions et données d'autres programmes. BeeBase fournit un port ARexx avec un nombre de commandes restreint mais néanmoins suffisant pour permettre à un programme externe d'effectuer des opérations comme si c'était BeeBase lui-même qui les effectuaient. De plus l'interface Arexx de BeeBase possède un mécanisme de transaction similaire à d'autres bases de données relationnelles.

Des exemples de scripts Arexx pour BeeBase sont disponibles dans `rexx'.

17.1 Nom du port

Le port ARexx dans BeeBase est nommé `BeeBase.n' où n est un compteur qui démarre à 1. Habituellement, si vous lancez une seule fois BeeBase, le nom du port sera `BeeBase.1'.

Vous devez déclarer le nom du port ARexx via address avant de lancer l'une des commandes ARexx de BeeBase. Le bout de programme suivant montre comment vérifier la présence du port ARexx dans BeeBase, comment lancer BeeBase le cas échéant, ainsi que comment interagir avec le port.

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

Consultez également l'exemple de script ARexx `address.rexx'.

17.2 Syntaxe des commandes

Après avoir contacté le port ARexx de BeeBase, vous pourrez lancer n'importe quelle commande ARexx de BeeBase. La syntaxe est similaire à celle d'autres implémentations :

cmd [arg1 ...]

où cmd est une des commandes décrites plus loin bas dans ce chapitre, et arg1 ... sont des arguments optionnels de cette commande.

Puisque l'interpréteur ARexx évalue la ligne de commande avant de l'envoyer à BeeBase, il peut être utile parfois de mettre entre guillemets certains, voire tous les arguments. Il est recommandé d'utiliser des guillemets simples (') pour les arguments qui ne seront plus utilisés ultérieurement par l'interpréteur ARexx. Ainsi vous pouvez toujours utiliser des guillemets doubles (") pour des arguments, par exemple pour des constantes de texte. De plus, vous pouvez intégrer la valeur des variables ARexx en leur enlevant leurs guillemets. Voici un exemple utilisant la commande BeeBase eval :

recherche = `'
eval handle 'select Nom from Personne where (like Nom "*'recherche'*")'

Consultez également Eval.

17.3 Codes retour

Après avoir lancé l'une des commandes ARexx de BeeBase, plusieurs variables ARexx sont mises à jour avec le résultat de la commande. Pour afficher tous les résultats d'une commande, vous devez activer l'option de résultats ARexx en ajoutant les lignes suivantes au début de votre script ARexx :

options results

Il existe 3 variables ARexx qui peuvent être définies par l'interface ARexx de BeeBase : rc, results et lasterror. La variable rc est toujours définie et indique le succès ou l'échec d'une commande. Si une commande est lancée avec succès, la variable results est initialisée avec le résultat de la commande alors que dans le cas d'un échec de la commande, la variable lasterror peut contenir des informations supplémentaires décrivant l'erreur.

Pour la variable rc il existe les codes de retour suivants :

Code retour  Signification

   0         Succès.  La variable result contient le résultat actuel.
  -1         Erreur d'implémentation. Ne devrait jamais se produire.
  -2         Mémoire insuffisante.
  -3         Commande ARexx inconnue.
  -4         Erreur syntaxique.
  -10        Autre erreur. Une description de l'erreur est donnée par lasterror.
  -11        Erreur interne. Ne devrait jamais se produire.
  -12        Erreur de compilation (uniquement pour la commande compile).

Dans le cas où rc <= -10, la variable lasterror contient une description valide de l'erreur. Des codes d'erreur supplémentaires pourraient être ajoutés dans le futur de façon à avoir un rapport d'erreur plus détaillé.

Voici un bout de code typique qui montre comment évaluer le résultat d'une commande ARexx de BeeBase :

eval handle 'select * from Comptes' 
if (rc == 0) then
    say result
else if (rc == -1) then
    say "Erreur d'implémentation"	
else if (rc == -2) then
    say "Mémoire insuffisante"	
else if (rc == -3) then
    say "Commande inconnue"	
else if (rc == -4) then
    say "Erreur syntaxique"	
else if (rc <= -10) then
    say lasterror
else
    say "Erreur : " rc

17.4 Quit

La commande quit provoque la fermeture du programme BeeBase. Veuillez également consulter la documentation de MUI.

17.5 Hide

La commande hide icônifie toutes les fenêtres ouvertes de BeeBase. Veuillez également consulter la documentation de MUI.

17.6 Show

La commande show désicônifie BeeBase et rouvre les fenêtres. Veuillez également consulter la documentation de MUI.

17.7 Info

La commande info retourne les renseignements suivants à propos de l'application MUI : titre, concepteur, droits d'auteur, description, version, port et écran.

Commande           Valeur de result

info title        Titre de l'application
info author       Concepteur de l'application
info copyright    Droits d'auteur
info description  Description
info version      Numéro de version
info base         Nom du port ARexx
info screen       Nom de l'écran public

Veuillez également consulter la documentation de MUI.

17.8 Help

La commande help écrit dans un fichier toutes les commandes ARexx disponibles de l'application MUI.

help nom-du-fichier

Les commandes ARexx sont affichées en respectant la syntaxe de l'interpréteur de commandes AmigaDOS. Veuillez également consulter la documentation de MUI ainsi que le manuel d'AmigaDOS pour la syntaxe de la ligne de commande.

17.9 Compile

La commande compile compile le code source d'un programme externe.

compile source [update]

Cette commande compile le fichier source d'un programme externe au projet dont le nom de fichier est spécifié avec la commande source. En cas de succès, la commande retourne la valeur 0, et si update est spécifié, le fichier source externe est réécrit. La mise à jour du fichier source permet la mise en évidence des mots clefs BeeBase. Un programme compilé avec succès est considéré comme le programme du projet et est utilisé lors de l'exécution de déclencheurs.

Dans le cas d'un échec lors de la compilation, le code d'erreur -12 est retourné et lasterror est défini sur 4 lignes de texte :

• La première ligne contient le nom du fichier qui a généré l'erreur.

• La deuxième ligne contient le numéro de la ligne où l'erreur s'est produite en commençant à 1.

• La troisième ligne contient le numéro de la colonne où l'erreur s'est produite en commençant à 1.

• La quatrième ligne décrit l'erreur sous forme de texte compréhensible.

Un projet doit absolument être déjà ouvert avant de lancer la commande compile pour compiler son code source externe. Si aucun projet externalisant son code source dans le fichier spécifié par source n'est trouvé, un code d'erreur <= -10 (mais différent de -12) est retourné et lasterror est défini.

17.10 Connect

La commande connect ouvre la communication vers un projet BeeBase.

connect nom-du-projet [GUI]

La commande vérifie en premier lieu si le projet défini par nom-du-projet est déjà ouvert et l'ouvre le cas échéant. Un projet n'est lancé qu'une seule fois et les diverses connexions vers le même projet partagent l'accès à la base de données. Ensuite un handle de communication (ou identifiant unique) est généré. Un handle de communication est une valeur entière non nulle. Si le mot-clef GUI fait partie de la ligne de commande, alors l'interface graphique du projet BeeBase est également lancée. Sinon aucune interface graphique n'apparaît ce qui permet d'exécuter des commandes ARexx de BeeBase en tâche de fond sans l'intervention directe de l'utilisateur.

En cas de succès, la valeur 0 est retournée et result prend la valeur du handle.

Exemple : `connect "BeeBase:Demos/Movie.bbs"' établit une connexion vers la base de données d'exemple de films.

Consultez également Disconnect, Connections, Codes retour.

17.11 Disconnect

La commande disconnect termine une communication existante.

disconnect handle

Termine la connexion à la base de donnée désignée par handle. Si c'est la seule connexion vers le projet référencé par handle et si le projet ne dispose d'aucune interface graphique, alors le projet peut être fermé et déchargé de la mémoire. Sinon le projet reste ouvert.

Exemple : `disconnect 1' termine la connexion ayant le handle 1.

Consultez également Connect, Connections, Codes retour.

17.12 connections

La commande connections donne des renseignements sur les connexions existantes.

connections

En cas de succès, connections retourne la valeur 0 et définit result sous forme de texte compréhensible dont chaque ligne est une connexion avec une valeur de handle et un nom de projet.

Exemple : la variable result après un appel à connections pourrait se présenter sous la forme suivante :

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

Consultez également Connect, Disconnect, Codes retour.

17.13 Eval

L'interface principale du port Arexx de BeeBase permettant la récupération et la mise à jour des données est gérée par la commande eval.

eval handle commande-lisp

La commande eval exécute la commande spécifiée par commande-lisp (écrite dans le langage lisp de BeeBase) sur le projet correspondant à handle. Un handle peut être obtenu via la commande connect. La commande commande-lisp peut être n'importe quelle expression du langage de programmation de BeeBase. La parenthèse la plus externe d'une expression est optionnelle et peut éventuellement être omise. Il est recommandé d'entourer commande-lisp de guillemets simples comme décrit dans Syntaxe des commandes.

En cas de succès, eval retourne la valeur 0 et définit result comme une chaîne de caractères de la valeur de retour de commande-lisp. La chaîne de caractères est faite de façon à avoir une idée du type de données retourné, par exemple un texte est entouré par des guillemets doubles alors qu'une liste est entourée de parenthèses dont les éléments sont séparés par des espaces ou des caractères retour chariot. Si vous voulez avoir un format spécifique, utilisez votre propre format dans la commande lisp spécifiée.

Si vous modifiez la base de données via la commande eval sans avoir auparavant lancé une transaction (voir Transaction) les changements deviennent automatiquement permanents (validation automatique). À l'inverse si vous avez lancé une transaction avant d'appeler eval les changements seront conservés en mémoire jusqu'à ce que la commande commit les rende permanents ou que la commande rollback les annule.

Exemple:

options results
address BeeBase.1
connect "BeeBase:Demos/Movie.bbs"
if rc = 0 then
do
    handle = result
    eval handle 'select Titre, Réalisateur from Films'
end
if rc = 0 then
    say result	    

Le résultat de l'exemple ci-dessus pourrait ressembler à ceci :

( ( "Titre" "Réalisateur" )
  ( "Batman" "Tim Burton" )
  ( "Batman Returns" "Tim Burton" )
  ( "Chérie, vote pour moi" "Ron Underwood" )
  ( "Tequila Sunrise" "Robert Towne" )
  ( "Mad Max" "George Miller (II)" )
  ( "Braveheart" "Mel Gibson" )
  ( "2010 - L'année du premier contact (L'odyssée continue)" "Peter Hyams" ) )

Consultez également Connect, Syntaxe des commandes, Codes retour, Transaction, Commit, l'exemple de script ARexx `movies.rexx'.

17.14 Transaction

Le port ARexx de BeeBase permet d'effectuer des transactions dans la base de données. Une transaction consiste en un ensemble d'opérations appliquées sur la base de données permettant la modification des données. Une transaction peut être soit exécutée et rendue permanente définitivement (commit), soit au contraire annulée à n'importe quel point de la transaction (rollback). On lance une transaction avec la commande suivante :

transaction handle

où handle fait référence à un projet obtenu par la commande connect (voir Connect).

Après lancement de la commande transaction vous pouvez accumuler autant de commandes eval que vous le désirez sans affecter la base de données. Pourtant il va vous falloir décider à un moment si vous voulez rendre les modifications permanentes (voir Commit) ou revenir en arrière, avant le lancement de la commande transaction (voir Rollback).

Après lancement de la commande transaction l'accès au projet correspondant est exclusif au handle spécifié. Ainsi, les autres programmes voulant accéder à la base de données (y compris l'utilisateur en passant par l'interface graphique) sont bloqués (ou différés dans le cas d'une autre connexion ARexx) jusqu'à ce que l'accès exclusif soit levé, en exécutant la commande commit ou rollback.

Habituellement la commande transaction retourne la valeur 0. Si une autre connexion ARexx requiert l'accès exclusif au même projet spécifié par handle, la demande est bloquée jusqu'à ce que l'autre connexion se termine soit en validant, soit en annulant la transaction.

Consultez également Eval, Commit, Rollback, Codes retour.

17.15 Commit

La commande commit s'utilise à la fin d'une transaction pour valider les changements de manière définitive.

commit handle

La commande commit met fin à une transaction (voir Transaction) en enregistrant le projet auquel fait référence handle. En cas de succès, la commande commit retourne la valeur 0. Si aucune transaction n'a été lancée avant l'appel de la commande commit ou s'il se produit une erreur, une valeur différente de 0 est retournée.

Consultez également Rollback, Transaction, Codes retour.

17.16 Rollback

Pour annuler les changements d'une transaction, utilisez la commande rollback.

rollback handle

Tous les changements effectués dans un projet référencé par handle depuis le début de la transaction en cours (voir Transaction) sont annulés et le projet revient à l'état où il se trouvait avant le lancement de la transaction. En cas de succès, la commande rollback retourne la valeur 0.

Consultez également Commit, Transaction, Codes retour.

Ce document a été généré le 30 Septembre 2024 par texi2html