MUIbase Support This Project
programmable relational database
with graphical user interface
This page is also available in deutsch english

Documentation

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


[ << ] [ >> ]           [Sommaire] [Table des matières] [Index] [ ? ]

17. Interface ARexx

L'interface ARexx n'existe que dans la version Amiga de MUIbase.

ARexx est une interface standard pour des programmes Amiga qui permet d'accéder aux fonctions et données d'autres programmes. MUIbase 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 MUIbase lui-même qui les effectuaient. De plus l'interface Arexx de MUIbase possède un mécanisme de transaction similaire à d'autres bases de données relationnelles.

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


17.1 Nom du port

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

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

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

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


17.2 Syntaxe des commandes

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

 
cmd [arg1 ...]

cmd est une des commandes décrites un peu plus 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 à MUIbase, 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 MUIbase 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 MUIbase, 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 MUIbase : rc, results et lasterror. La variable rc est toujours définie et indiquer le succès ou l'échec d'une commande. Si une commande est lancée avec succès, la variable results est initialisé 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.
 -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 MUIbase :

 
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 MUIbase. Veuillez également consulter la documentation de MUI.


17.5 Hide

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


17.6 Show

La commande show désicônifie MUIbase 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 MUIbase. 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 MUIbase.

 
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 parti de la ligne de commande, alors l'interface graphique du projet MUIbase est également lancée. Sinon aucune interface graphique n'apparaît ce qui permet d'exécuter des commandes ARexx de MUIbase 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 "MUIbase:Demos/Movie.mb"' établit une connexion vers la base de données d'exemple de films.

Consultez également Disconnect, Connexions, 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, Connexions, Codes retour.


17.12 Connexions

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 MUIbase:Demos/Accounts.mb
   5 MUIbase:Demos/Movie.mb
   6 MUIbase:Demos/Movie.mb
   7 MUIbase:Demos/Movie.mb

Consultez également Connect, Disconnect, Codes retour.


17.13 Eval

L'interface principale du port Arexx de MUIbase 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 MUIbase) 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 MUIbase. La parenthèse la plus externe d'une expression est optionnelle et peut éventuellement être omise. Il est recommandé d'entourer commande-lisp par des 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 MUIbase.1
connect "MUIbase:Demos/Movie.mb"
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 MUIbase 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

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.


[ << ] [ >> ]           [Sommaire] [Table des matières] [Index] [ ? ]

Ce document a été généré le 11 Septembre 2016 par texi2html