Manuel de référence de programmation du module Transact

Table des matières

Objectif du document

Ce document décrit les SWIs qui sont couramment fournis par le module Transact et donc peuvent être utilisés par une application cliente désirant s'interfacer à ce niveau. Notez cependant qu'un autre document décrit l'API C au dessus de Transact et que l'usage de cette dernière est recommandée pour des applications cliente écrites en C.

Généralités

Fonctionalités offertes

Le module Transact permet un accès transactionnel et concurrent de façon uniforme et cohérente à des ressources de données disponible dans l'environement de l'application (aujourd'hui uniquement les fichiers plats sont considérés). Plus de détails à propos des capacités du moteur Transact peuvent être lus dans le document "Gestion transactionnelle pour l'accès à des fichiers plats" qui se trouve dans la même distribution que le docment que vous lisez.
Typiquement, une application cliente désirant apporter des changements à plusieurs fichiers de données RISC OS dans un mode transactionnel procédera comme suit:

Ouvre une session (lors de l'initialisation); Une création de session déclenche automatiquement le début d'une transaction;
Soumet les requêtes de lecture/écriture adhoc (cad telles que prévues par l'API);
Termine la transaction, soit en validant les écritures, soit en abandonnant toute écriture soumise depuis le début de la tranaction. Bien entendu, le module prend soin de ne pas perturber les transactions concurrentes même si elles écrivent dans les mêmes fichiers que la trnsaction courante.
Ferme la session (aussitôt que l'application n'a plus besoin des services Transact).

Conventions d'appel

Détails d'implémentation

L'interface du module Transact pour accéder aux ressources système est basé sur l'utilisation de la librairie partagée CLib d'Acorn. Le module a été généré avec l'aide des outils standard Acorn (CMHG et Acorn C v5.06);
La version courante du module n'utilise pas la fonction de la librairie partagée CLib pour masquer les interruptions. En conséquence il est possible (et cela peux s'avérer dangereux) qu'un SWI Transact soit appelé (par exemple d'une routine de traitement d'interruption) alors que un SWI du module Transact est en cours d'exécution en mode "foreground". Une version ultérieure du module corrigera cette faiblesse en appelant lui même une fonction utilisant l'instruction SWP qui est disponible depuis la sortie de l'ARM3 (pour la gestion des sémaphores). Les SWIs de Transact sont enregistrés auprès de Acorn, vous pouvez donc utiliser sans risque le module Transact en concurrence avec d'autres modules enregistrés ou non.

Que se passe-t-il lorsque le module Transact est tué?

Toutes les sessions ouvertes sont fermées; les transactions actives (en cours) sont abandonnées (rollbacked) et les fichiers de donnée sont rendus disponibles pour toute autre application.

Référencement des fichiers RISC OS

Dès qu'un appel SWI référence un fichier RISC OS, les conventions suivantes s'appliquent:

R0 = ID externe de session (tel que retourné par le SWI Transact_CreateSession);
R1 = ID externe de fichier RISC OS, pointeur sur le nom de l'objet; ce nom est GSTRansformé; A partir de là, le nom GSTransformé sert de clé pour discriminer les fichiers RISC OS par leur nom. La version actuelle du module requiert que le nom GSTransformé désigne un chemin complet et non seulement la partie terminale car aucun travail de complétion n'est effectuépar le module Transact.
R2 = Pointeur sur un ID interne (scalaire) qui est alloué paar le module pour de futures références au même fichier;

La partie frontale du module exécute le pseudo-code suivant:

Si R1 <> 0 Alors
	Conversion du nom de fichier (ID externe dans R1): GSTransformation;
	Rechercher une entrée correspondante dans la liste des entrées existantes;
	Si trouvé Alors
		Utiliser cet emplacement pour les opérations suivantes.
	Sinon	Create a new entry in the system for this file (never refered to before)
	FinSi
	Si R2 <> 0 Et valid file entry Alors
		*R2 = handle du fichier de données (résultat d'un appel à fopen)
	FinSi
Sinon	/* R1 = 0 */
	Si R2 = 0 Alors
		Erreur sortie "Paramètres invalides"
	FinSi
	Rechercher dans la liste des fichiers déjà répertoriés une entrée avec le même ID interne (*R2);
	Si non trouvé Alors
		Erreur sortie "Objet inconnu"
	FinSi
FinSi

Appliquer cette procédure peut impliquer l'échec pour l'une des raisons suivantes:

&812B03 Paramètres invalides si R1 et R2 sont tous les deux à zéro.
&812B06 Erreur de conversion (lorsque R1 <> 0);
&812B02 Objet inconnu: R1 = 0; R2 <> 0; Pas d'entrée correspondante à *R2 dans la liste des ID internes.