Transact module Programming reference manual

Transaction Module Programming Reference Manual

Table of content

Document goal

This document describes the SWIs which are currently provided by the Transact module and thus can be used by a client application wishing to interface itself at this level. Note however that another document describes the Transact C API functions and the use of the latter is recommended for client applications written in C.

Overview

Provided facilities

The Transact module allows an harmonious and uniform form of concurrent and transactionnal access to data ressources in the application environment (currently only flat files are concerned). More details about the abilities of the Transact "engine" can be found in the document "Transaction processing for flat file access" which is in the same distribution pack as the document you are reading.
Typically a client application willing to make changes to several RISC OS data files in a transaction mode will proceed as follows:

Opens a session (at the initialisation time); A session creation automatically triggers the begin of a transaction;
Submits the adhoc reading and writing requests (i.e. as provided by the API);
Ends the transaction, either by validating all the writes, or by canceling every submitted write since the beginning of the transaction. Of course the module takes care not to "disturb" concurrent transactions even if they write to the same files as the current one.
Closes the session (as soon as the application doesn‘t require any Transact module's servicing anymore).

Call conventions

Implementation details

The Transact module's interface with the system resources is based on the the Acorn C shared library use and has been generated using the standard Acorn tools (CMHG and Acorn C v5);
The current release of the module doesn‘t use the C shared library's functions to mask out interrupts. Therefore it is possible (and this may be a dangerous situation) that a Tansact module's SWI be called (f.e. from an interrupt processing routine) while a Transact module SWI is in progress. A future release of the module will take care of this flaw by calling a function itself using the SWP opcode which is available since the advent of the ARM3 (for semaphore management). Transact SWIs are registered, so you can safely use the module with other registered modules.

What happens when the Transact module is killed?

All open sessions are dropped; active transactions are rollbacked and the main data files are "released" for use by other programs.

RISC OS file referencing

Whenever a SWI call interface references a RISC OS file, the following convention applies:

R0 = External session ID (as returned by the Transact_CreateSession SWI);
R1 = RISC OS file's external ID, pointer to the object name; this name is GSTRansformed; From then, the GSTransformed name serves as a key for comparing the object names. The current release of the module requires that the GSTtransformed name deignates a full pathname and not only a "leafname" as no completion work is performed by the Transact module.
R2 = Pointer to an internal ID (scalar) which is allocated by the module for future references to the same file;

The frontal part of the module runs the following pseudo code:

If R1 <> 0 Then
	Filename conversion (externnal ID in R1): this is the GSTransformation;
	Lookup in the existing system list for a match;
	If found Then
		Use this slot for the subsequent operation
	Else	Create a new entry in the system for this file (never refered to before)
	EndIf
	If R2 <> 0 And valid file entry Then
		*R2 = Main data file handle (result of an fopen call)
	EndIf
Else	/* R1 = 0 */
	If R2 = 0 Then
		Error exit "Invalid parameters"
	EndIf
	Lookup in the existing system list for a match(an entry with the same  internal ID (*R2)
	If not found Then
		Error exit "Unknown object"
	EndIf
EndIf

Applying this procedure can imply the failure of a servicing call for one of the reasons below:

&812B03 Invalid parameters if both R1 and R2 equal to zero.
&812B06 Conversion error (when R1 <> 0);
&812B02 Unknown object: R1 = 0; R2 <> 0; there is no match for *R2 in the system list as an internal ID.