Transact Engine Tutorial
(WIMP interface)

How to make an effective use of the Transact material provided here for the RISC OS range of computers (recommended reading before programming over the Transact Engine).

Table of Content

Warning
Prerequisites
Material overview
Concurrent access: basic concepts
Transaction modes: basic concepts
- DIRTY READ mode
- REPEATABLE READ mode
Miscellaneous topics
- Result sets and cursors
- Compound requests
Troubleshooting guide

Warning

This tutorial is written for the 0.2.2 release of the Transact engine as part of an effort from the author to help other people understand the main abilities of the Transact module. You should not take for granted the continued developing effort of this tutorial as part of the Transact engine itself. However, I'll be happy to communicate with those of you who would like to comment this document or simply request for further explanation on a specific topic related to the document.
My email is:
bgilon@free.fr
My native language is not English so be indulgent;

Prerequisites

You should have is a RISC OS based computer running Risc OS 3.10 or later. I did'nt make any testing with a RO2 machine (too lazy to retrofit my A410/1 from RO3.1 to RO2): In case you are sticked to RO2 or RO3.0, I strongly recommend you upgrade to RO3.1.
An additional prerequisite for running the tutorial is the possession of the Acorn toolbox modules which are loaded by the !Transact tutorial applications using the OS System path environment variable. In case you don´t have them, then let me know about this and I'll try to include them in a future update of the Web site from where you downloaded this tutorial.

Material overview

Inside the archive, you'll find several application and directories which hold everything you need to make the "exercices";
Here is the role of some of the objects laying there.

Application/File name	Purpose
DataFile	Main data file: currently only 4 characters "abcd" but you can change its contents either from inside the Transact programs or from a stand alone editor (such as !Edit).
FileInsert	File used by the menu program to insert characters at the end of the main datafile: currently only 4 characters "Véro" but you can change its contents by using an external editor (such as !Edit).
FileUpdate	File used by the menu program to replace some of the original characters with new ones: currently only 2 characters "cb" but you can change its contents by using an external editor (such as !Edit).
!TrnServer	Application which converts WIMP based requests to SWI calls to the Transact engine. Techies used to name such components as "proxies". This application should run for the whole time of the lessons. When such applications starts, it RMEnsure the Transact engine module and RMLoad it from a local copy if not previously active.
!TrnClient	Application which allows users to submit requests to the Transact engine via GUI components. !TrnClient dialogs with !TrnServer following a WIMP message based protocol.

Concurrent access: basic concepts

The "liberal way"

As your computer is up and running, launch the !Edit application twice in the !Apps folder so that two icons reside on the icon bar as active tasks.

Drag the Datafile to each of the icons. Two separate windows should popup.
Modify the text content in the first window and then save it (use the F3 Return shortcut)
Save the content of the second window to the same file (again use the F3 Return shortcut) (with no or different changes than previously applied);
Close the two document windows;

Now shift-double click over the file icon in the File directory viewer; you may have noticed that the changes applied in the first document window has been lost since the second save operation;
Now imagine that the second window was opened by someone having access to your workfiles via a network.
This scheme offers no protection in term of lock management: when a data of a file needs to be updated some way then:

All the data are read from the media into memory;
The update is done in memory;
At an arbitrary time, the whole content is saved to the file.

Result: concurrent updates wich occured in the meantime are overwritten.

The "conservative" way

Well, in this example, we are using the !TrnClient program as a dumb file locker (every action and term used in this exercise will be explained further in relevant sections).

Launch the !TrnServer application if not already there on the iconbar;
Launch the !TrnClient application if not already there on the iconbar;
Click the Menu button over the !TrClient icon. The menu below popups:
Click over the "New Session" entry in the menu, the dialog box below should appear:
From now on, click SELECT over the OK button and the session's main window will pop up.
- Choose a Select operation in the action menu
- Drag the Datafile icon in the Datafile filename writefield
- Leave the "Bidirectional cursor" option button unseletected
- Drag the End slide bar to 4.
The window should look like this:
Click on the Submit Action button, if all goes well, the cursor ID window field should be refreshed with the newly created cursor's ID.
Now that the Transact engine has opened the file for update, shift doucle-click on the icon of the Datafile and see what happens then;
A warning dialog box stating that "This file is already open" pops up.

Result: while a file is being opened for update mode by an application, no other application can have access to this file (QED).
To allow other apps to make their own changes to the same file, the transact engine has been enhanced in its 0.2.1 release and hence the menu entry "Release file" in the "Action menu".

The "transactional" way

You guess it: that is using the Transact engine!
You will be able to retrieve the entire file' content in memory for editing while locking the whole against concurrent writes (better than the "liberal" way);
You will be able to do online changes w/o forbidding other applications from accessing disjointed parts of the same file for writing and the whole part of the file for reading!
Let's illustrate the hidden potential by emulating two client applications accessing the same file.

Create two sessions using the !TrnClient iconbar menu (the sessions will be of the "READ_COMMITED" kind);
Initiate an UPDATE operation in the name of the first session:
- Select the Update entry in the action menu;
- Drag the Datafile icon on the Datafile filename writefield icon;
- Drag the icon of the FileUpdate file on the Operation filename icon;
- Drag the Begin slide bar so that it shows the digit 1; that's mean that the letters "bc" in the original datafile are at least temporarily and for the sole session's view replaced to "cb";
- Click on the Submit action button to send this request to the engine.
Commit the UPDATE operation by selecting the Commit entry in the Action menu and then clicking on the Submit ACtion button.
Initiate a SELECT operation for the second session:
- Choose the SELECT entry in the action menu of the second session window.
- Drag the Datafile icon on the Datafile filename writefield icon;
- Check the result in the app #1 task window by initiating a SELECT operation begin offset 0, end offset 4, cursor mode Forward Only; The lines below should be displayed:
```
zdebut 0 zfin 1 type 0	!read from the main data file
<a>
zdebut 1 zfin 3 type 2	!read from the log file (pending writes waiting to be validated|rejected)
<cb>
zdebut 3 zfin 4 type 0	!read from the main data file
<d>
Terminate the SELECT operation? (Y/N)
```
  Type Y to terminate the SELECT operation and hence close the cursor;
- In the app #2 window, initiate a SELECT operation (option #8) begin offset 0, end offset 4, cursor mode Forward Only; The lines below should be displayed:
```
zdebut 0 zfin 4 type 0	!read from the main data file
<abcd>
Terminate the SELECT operation? (Y/N)
```
  Type Y to terminate the SELECT as usual;
  Partial conclusion: we have seen that a write operation does not lock concurrent read operations on the same data. That's a benefit from the multi-versioning system (please refer to the document "Transactional access to flat files" which is part of the same package as the document you're reading for more info). Also you may have noticed that you have selected READ COMMITED for the transaction mode of the session opened in the app #2, that's why the active transaction in the app #2 does not "see" pending writes of concurrent transactions before they are validated.
- In the app #2 window, initiate a SELECT FOR UPDATE operation (option #9) and specify the same parameters as above; this time, the operation should be less successful and the message below should be displayed:
```
Erreur #2010007
Conflict with another session
```
  The SELECT FOR UPDATE is like a normal SELECT except that the client app specifies its intent to update the data involved in a subsequent operation and hence has the same effect as an UPDATE request regarding the lock management. Therefore the message returned is to be considered normal given the fact that another program (app #1) held an update lock on bytes #1 and #2 of the main data file (starting from byte #0);
- To make things "work", reduce the "range" of our SELECT FOR UPDATE operation, reitereate the previous step but this time specify an end offset of 1 (only retrieve the first byte of the data file).
```
zdebut 0 zfin 1 type 0
<a>
Terminate the SELECT operation? (Y/N)
```
  Type Y to terminate the SELECT as usual;
  Byte #0 ("a") is not involved in any pending write operation in the name of a concurrent transaction hence the absence of a conflict in this case.
- Before proceeding on the next chapter, we'll clean things up a bit! type 3 to drop the current session in the app #2 task window but keep the app #1 unchanged as the resulting configuration will serve soon.

The DELETE and INSERT operations are very simple to use; for the DELETE operator, the user has to enter the offset of the first byte relative to the beginning of the file chunk to remove.

Transaction modes: basic concepts

Briefly stated, the transaction mode (choosen as the session is created) acts upon the way the transactions view the main data files regarding to concurrent transactions.
In the previous chapter, we have seen that a READ COMMITED transaction mode session does not see "concurrent pending changes" until the concurrent transaction is validated.
In this chapter, we will show how DIRTY READ and REPEATABLE READ mode sessions behave.

DIRTY READ mode

From the main menu in the second task window (app #2), create a new session and selects DIRTY READ mode as its transaction mode;
Initiate a SELECT operation (option #8) an specify a begin offset 0, end offset 4 and Forward Only: The lines displayed should look like these:
```
zdebut 0 zfin 1 type 0
<a>
zdebut 1 zfin 3 type 2
<cb>
zdebut 3 zfin 4 type 0
<d>
Terminate the SELECT operation? (Y/N)
```
Type Y to terminate the SELECT as usual;
Rollback the transaction originated from app #1 (currently with a pending UPDATE request) by selecting option D;
Reiterate the SELECT operation in app #2 task window (same entry parms as above); You should then see the following lines being displayed.
```
zdebut 0 zfin 4 type 0
<abcd>
Terminate the SELECT operation? (Y/N)
```
Type Y to terminate the SELECT as usual;
Conclusion: well, here we show that a DIRTY MODE transaction can see transient states in the data file life that is, it can read not yet validated changes which source is a concurrent transaction (from app #1 in this case).
To clean things up, drop the active session (option 3) in the app#2 task window.

REPEATABLE READ mode

In the app #2 task window, create a session and select REPEATABLE READ as its transaction mode;
Initiate a SELECT operation in app #2 task window, params are: begin offset 0, end offset 4 and cursor mode: Forward Only. You should see the lines below:
```
zdebut 0 zfin 4 type 0
<abcd>
Terminate the SELECT operation? (Y/N)
```
Type Y to terminate the SELECT as usual;
Initiate an UPDATE operation in app #1 task window, params are: offset 1;
Initiate a COMMIT operation in app #1 task window; The datafile content now is "acbd";
Initiate a SELECT operation in app #2 task window with the same parms as in step 2; You should see the lines below:
```
zdebut 0 zfin 4 type 0
<abcd>
Terminate the SELECT operation? (Y/N)
```
Type Y to terminate the SELECT as usual;

Conclusion: despite the fact that the data file content has been changed in between, the transaction's view of the data will never change apart from its own write request once it as been read. Of course at the beginning of the next transaction the change will be taken into account.

Miscellaneous topics

Result sets and cursors

Some facts to keep in mind:

A result set is built as a successful result of a SELECT or SELECT_FOR_UPDATE SWI call;
Only a result set per session per data file exists: If an application tries to create a result set as a previous result set exists (created by this session on the same file), then an error "Cursor in use" is returned.
An application can create a result set as a new transaction begins or after a Transact_AllDone SWI is submitted (which deletes the current result set).

To illustrate this:

Start an app (app #1) by double-clicking on the !Run1st icon;
Create a new session (READ COMMITED)
Initiate a SELECT operation begin offset 0, end offset 4, cursor mode Forward Only; the lines below should be displayed:
```
zdebut 0 zfin 4 type 0	!read from the main data file
<abcd>
Terminate the SELECT operation? (Y/N)
```
The lines above are displayed as part of a call to a debugging SWI and not to the normal FETCH SWI call, so type N this time;
Initiate a Fetch operation on the newly created cursor (option A of the main menu). Start offset 0, End offset 4. The lines below should be displayed.
```
p_fetch return status 4
<abcd>
4 characters have been fetched succesfully.
```
Reiterate the same Fetch operation with the same parameters; This time an error should occur:
```
Error #33619974
The selected cursor mode doesn't allow such operation
```
However, rereading the same data would work for a "Allow backwards" cursor mode result set; try it if you like by selecting option B to end dealing with the current result set and then repeat from step 3 but this time select an "Allow backwards" cursor mode when creating the result set.

Compound requests

Compound requests (introduced since the v0.2.1 release of the Transact engine) allow a client application to submit multiple write requests at the same time (that is in a single call).
We should focus on the fact that using compound requests currently is the only way to set intermediary rollback points as we'll see in the following example:

Start an app (app #1) by double-clicking on the !Run1st icon;
Create a new session (READ COMMITED);
Initiate an INSERT operation in this task window;
Launch a second instance of the client application (app #2) by double clicking on the !Run icon and create a new session the usual way;
Initiate an UPDATE operation on the behalf of the newly started client app; parameters are begin offset 1;

Initiate a compound request in the app #2 task window (option G); a specific menu should appear for specifying all the components of our compound request:

 Compound MENU
 -------------

1 - INSERT operation
2 - UPDATE operation
3 - DELETE operation
F - FINISH the data entry and call the Transact Engine
Q - Cancel the compound request and return to the MAIN MENU
Your choice ? :

Enters an UPDATE operation (option #2) from offset 0 at first;
Then enters an INSERT operation (option #1);
Choose option F to submit the two request in a row; The message below sould be displayed:
```
Error #33619975
Conflict with another session
```
This message can be explained: we tried to insert bytes in a datafile as a pending insert exists as a part of an active concurrent transaction.
From the main menu in the app #2 task window, initiate a commit operation (remember that we initiated an UPDATE operation in step 5 as the first operation of the current transaction).
From the main menu in the first task window, initiate a SELECT operation; the result should be something like:
```
zdebut 0 zfin 4 type 0
<acbd>
zdebut 4 zfin 8 type 4
<V�ro>
Terminate the SELECT operation? (Y/N)
```

Conclusion: Althrough the compound request failed, the result was not a rollback to the begin state of the current transaction but only to the state of the transaction as the compound request was submitted. QED.

Troubleshooting guide

Unknown object error while running the client menu program The menu program always refer to the Obey$Dir environment variable; however, as applications are launched in your desktop: this variable is subject to multiple changes over time; this may imply that its value points to a directory unrelated to the Tramsact module at the time a request is submitted; If so an error is returned by the Transact engine saying "Unknown object"; To make things work again, all you have to do is to double-click on the ObeyFile inside the TransactM.client directory.

Transact Engine Tutorial(WIMP interface)