How to Use the Transaction Simulator

The main executable is called "Mars.exe" and it makes use of the following files in its working directory:

• diskfile - This contains the pages that actually make up the database, written in sequential order. Each page consists mostly of data, with a small amount used for containing the pageLSN. For simplicity, all data entries on a page are just integers, and all operations reflect changes to one of the integers on a page.

  ourlog - This contains all the log data that has been written to disk. To make things simple, the simulator currently writes all log records to disk as soon as they are made. The recovery manager usually ignores what was lost in the tail of the log when the crash occurs, so you won't have to worry about the distinction between the tail and the log on disk. In a real database, however, the log usually has a tail that is kept in memory, and some extra measures must be taken to insure that the log is written to stable storage when necessary.

  master - This contains the checkpoint data used in determining the lsn from which the recovery is to start.

  To start the simulator, you can double click on Mars.exe. You will then be presented with a UI containing a toolbar and the standard menu on the top row of the screen.

  The toolbar contains three buttons:

  - The button with the folder icon allows you to load a test file (to be explained below).

  - The sideways arrow button allows you to step through the test file.

  - The downward arrow button runs the test file in its entirety.

  - The X button resets the database being simulated.

Input Syntax

The simulation runs by executing a series of operations that model the behavior of a set of transactions. These operations are loaded from .mars files. There are 9 .mars file given in the Tests folder and of course you can compose your own if you want. The syntax is pretty simple and are described below. I recommend looking at the test files given as the fastest way to learn how to create them.

Operations are given with the following syntax. A semicolon is used to mark the end of a command, and spaces are used to separate arguments.

• Transaction begins - A transactions must be "declared" before it can perform any operations. Transactions are identified by a string given when they start, in a command with
  form: <transaction name> tbegin;
  Example: t1 tbegin;
• Reads - A read extracts a data integer from the given page and offset. Offsets are counted in data entries, so an offset of 2 represents the third integer on a page.
  form: read pageId offset
  Example: read 3 4;
• Writes - The given integer is written to a given page and position.
  form: <transaction name> write pageId offset newData
  Example: t1 write 0 4 10;
• Commits - The given transaction commits and is removed from the list of active transactions
  form: <transaction name> commit
  Example: t1 commit;
• Aborts - The given transaction is completely rolled back and removed from the list of active transactions
  form: <transaction name> abort
  Example t1 abort;
• Crash - The simulator is terminated, leaving any active transactions in an unfinished state
  form: crash;
• Restart - The simulator uses the information in the log to perform the Aries recovery algorithm, restoring the database to its last pre-crash state then rolling back all uncommitted transactions.
  form: restart;
• Checkpoint - Generates a checkpoint consisting of the Dirty Page Table and Xaction Table, and writes into both the log and masterlog.
  form: checkpoint;
• Pageflush - This force flush the specified page to disk.
  form: pgflush <page id>;

Getting Started

To become familiar with the code, I suggest you load either Test 1, 2, or Test 3 given in the Tests folder. The syntax is quite simple and if you step through the test files you will gain intuitive understanding how the transaction simulator works. There are comments in the given test files that tell you what the correct values of the reads should be. These are strings preceded by the # sign.