********************************************
     Project 1 - Modified IRIS Program
       CS525 - Sec 2 - Adv DB Org

              Steve Talbot
            talbste@iit.edu
             847.436.0815

                README

********************************************

1) System Requirements

(a) Development Environment: 

    - AMD Sempron 1.8 GHz microprocessor
    
    - Ubuntu 8.04 Hardy Heron Linux Operating System
    
    - Eclipse ver. 3.2 Linux edition

(b) NOTE: This application will not work in Windows OS Environment,
    without re-compiling from source code.  Making some minor 
    modifications to the "UserInterface" component would then
    also be suggested.


2) Files (see also "5) File Output / System Files" below)

(a) "..\CS525_Project_1_Spring_2009_Talbot_Steve.zip"

	This archive contains:

		- the README file
		
		- "Project_1_stalbot" folder, which contains the source code
		  (developed using Eclipse ver. 3.2 for Linux, C++ plug-in / CDT)

		- "Project 1" file, which is the executable.
		
		- "batch_test_1.txt" file, which is a test batch file

	Right-click this archive.  Select "Extract files".  Keep the 
	default settings presented in the window that appears.
	Select the directory in which to extract the files from 
	this archive.  Click "OK".

	These files will be extracted to the location that you 
	have selected.


(b) "..\Project_1"

	".metadata"

	"Project_1"
	
		".settings"	Eclipse configuration file
		
		"Aggregations"	Various value objects
		
		"Buffer"		Utility classes for BufferManager (BIT)
		
		"Catalog"		Utility classses for CatalogManager
		
		"Database"	Utility class for StorageManager
		
		"DataHeader"	Utility class for StorageManager
		
		"DataPage"	Utility class for StorageManager
	
		"Debug"		Eclipse files, location of executable
	
		"Managers"	Layer drivers (UserInterface, QueryManager, StorageManager, etc)
		
		"Testers"		Test classes
		
		"UserInterface"	Top layer / user interface component
		
		"Utilities"		Miscellaneous utility functions
		
		
		"DatabaseManagementSystem"	Top layer driver component
						This is the component where 
						the function "main()" is located.
	

3) Running the program

NOTE: This program was compiled on a Linux-based machine.
      The executable will only function on this type of machine.
      Attempting to execute this machine on a Windows-based machine
      will have a successful result.
      
NOTE: Please see "4) Commands, (l) Set Path" for an important and vital
      note about configuring the application upon every startup".
	
(a) Command Line

	1) Navigate to the directory where you have placed the 
	   executable file "Project_1".
	   
	2) This directory is NOT necessarily the directory
	   in which system files will be stored.  
	   
	   a) Please see the section below entitled: 
	      "4) Commands, (l) Set Path"
	   
	   b) The system was setup to have "/home/" 
	      as the default directory for system files 
	      (table files, header files, catalog file).
	      
	   c) If you wish to have the system files created in the same
	      directory as the location of the "Project_1" exectuable,
	      simply place "Project_1" in the directory "/home/", or
	      use "set path" System command to change the system path
	      to match the directory where you've placed "Project_1".
	
	3) Type the command "./Project_1 X"
	
	   a) "X" should be replaced with the number of main memory 
	      buffer pool pages that the system will use will running.  
	      
	   b) This value should be a positive integer number less than 
	      2,147,483,648.  The larger this number, the faster the 
	      application  will perform, but the more main memory the 
	      application will hog.  If this argument is not provided, 
	      the System default is 3.
	      
	   c) The prefix "./" is needed to tell the OS that the
	      application is located in the current directory.
	      If the User wishes, they may replace this prefix
	      with the fully-qualified location of "Project_1",
	      instead.
	
(a) Eclipse IDE

	1) Start Eclipse
	
	The "Select a Workspace" window appears.  Select the location 
	of the directory folder "Project_1".

	This "Workspace" folder should contain the ".metadata" and 
	the "Project_1" folders.

	Eclipse should show the project, titled "Project_1", in the 
	"Package Explorer" FileChooser in the left hand side view.

	(If this is not the case, try the alternative approach "2)" 
	that follows .. else skip ahead to "3)").

	
	OR


	2) Select a "Workspace" where a new project will be created.

	Create a new "C++ Project" in Eclipse via selecting 
	"File->New->Project".  Select "Managed Make C++ Project".  
	Click "Next".

	Type a project name ("Project_1") and select all default values by 
	selecting "Next" 2 times, or just select "Finish".

	Right-click the project, and select "Import" (now that 
	the project is created, we need to fill it with the files 
	of source code).

	"Browse" to the directory where the source code files are 
	located, select "General->File System", click "Next", 
	click "Browse".
	
	Navigate to the folder "..\Project_1_stalbot\Project_1".  
	In the window that appears, check the box next to the folder 
	"Project_1".  This should include all the ".cpp" source files 
	appearing in the nested directories.  Click "No" when asked 
	to overwrite files.  Click "Finish".

	Press "Finish" and the files should appear in the 
	"Package Explorer" FileChooser view on the left-hand side 
	under the newly created project folder.
	

	3) Optionally, the user may supply command line arguments.
	
	Right-click the project named "Project_1", and select
	"Run As->Run.."  Alternatively, click the drop-down menu
	"Run->Run".
	
	The window entitled "Create, Manage, and Run Configurations"
	should open.
	
	In the left-hand menu under "C/C++ Local Application",
	there should be a configuration called "Project_1"
	or something similar.  Click on this configuration.
	
	Click the tab entitled "Arguments".
	
	Enter the number of main memory buffer pool pages
	that the system will use will running.  This value
	should be a positive integer number less than 2,147,483,648.
	The larger this number, the faster the application
	will perform, but the more main memory the application
	will hog.  If this argument is not provided, 
	the System default is 3.
	
	
4) Commands

The following descriptions discuss SQL commands and System commands that
are recognized by the System.  All commands are "case-insensitive".

(a) "create"

	1. Creates a table entry in the "catalog.bin" file.
	
	2. Creates the file "tableName_header"

		a. create table [ tableName ]( columnName1, .. columnNameMax )

			1. "create table xyz(aa, bb, cc)"

(b) "insert"
	1. Inserts a record into the table.
	
	2. Records typically are not saved / written to file unless the user 
	   periodically issues the "commit" command ( see "(d) commit" ).
	
	3. However, if the buffer of records in main memory is full, 
	   further inserts will flush (save / write) the buffer records to file 
	   to make room for the new insert in the buffer.
	

		a. insert into [ tableName ] values( value1, .. valueMax )

			1. "insert into xyz values( 10, 20, 30 )"

(c) "select"

	1. Retrieves records from both the main memory buffer and the file for display.

		a. select * from [ tableName ]

			1. "select * from xyz"

		b. select [ columnName(s) ] from [ tableName ]

			1. "select aa, cc from xyz"

		c. select [ columnName(s) ] from [ tableName ] where columnName = value

			1. "select bb, cc from xyz where aa = 5"

		d. select [ columnName(s) ] from [ tableName ] where columnNameX = value and columnNameY = value and ..

			1. "select aa, bb from xyz where aa = 5 and cc = 17"

		e. select [ columnName(s) ] from [ tableName ] where columnNameX = columnNameY and columnNameY = columnNameZ and ..

			1. "select aa, cc from xyz where aa = bb and bb = cc"

	2. If the main memory buffer is full, the System will either flush or overwrite 
	   one or more pages in the buffer prior to a retrieving the necessary pages from file.

(d) "commit"

	a. Flushes (saves / writes) the contents of the main memory buffer to file.

		1. "commit"

(e) "print catalog"
	
	a. Prints the contents of the "catalog.bin" file to screen.  

		1. "print catalog"

(f) "print table"
	
	a. Retrieves records from both the main memory buffer and the file for display.
		
	b. Equivalent to the "select * from [ tableName ]" command.

		1. print table [ tableName ]

			a. "print table xyz"

(g) "print buffer"
	
	1. Print information about the buffer pool, including "buffer #", 
	   "table name" and "block # / pageID"

	    a. "print buffer"

(h) "print buffer data"
	
	1. Print the current contents of the buffer pool, 
	   grouped by "table name" (but not by bp block)

	   a. "print buffer data"

(i) "print hit rate"
	
	1. Prints the "hit rate", where
		
	   a. "total # of block requests"
		
		1. The sum of requests for blocks from the buffer pool 
		   ("hits") and pages from the table file ("misses").
			
	   b. "# of hits"
			
		1. (total # of block requests)  (# requests read from file)
			
	   c. "hit rate" = (# of hits) / (total number of block requests)

(j) "set timer on"
	
	1. The duration of each operation is displayed in milliseconds.

	   a. "set timer on"

(k) "set timer off"
	
	1. The duration of each operation is not displayed.
		
	2. This is the default of the application upon startup.

	   a. "set timer off"

(l) "set path"
	
	1. Change the drive and directory path that the system uses to
	    look for and write System files (table, header, catalog).

	   a. "set path [ pathname ]"

		1. windows pathname = "C:\databasefiles\myfiles"
				
			System considers ":\" and "\" to be token delimiters,
			so a user could simply enter "C databasefiles myfiles"
			and get the same result as above.
				
		2.   linux pathname = "/home/myHome"
				
			System considers "/" to be token delimiter,
			so a user could simply enter "home myHome"
			and get the same result as above.
					
	2. "/home/"
			
	   a. This is the default path that the system starts with,
	      where the application expects to find system files 
	      (see "File Output" below).
				
	   b. NOTE: It is expected that at the start of every session,
	      the user will need to set the path.  If the user
	      recieves vexing error messages, this is likely the cause.
	      Shutdown the application, erase any errant files
	      that were created (using the OS file system),
	      restart the application and remember to set the path
	      right away before proceeding.
	      
	   c. The User may wish to write the application path name
	      to a text file to save for future use, or in order
	      to quickly cut and paste into a terminal window
	      if the User plans on performing several re-starts.
	      
	3. System files
	
	    a. The System expects to see the system files 
	       (table files, header files, catalog file) in this
	       directory.
	       
	    b. The System does not currently support deleting files,
	       either through the application or through the OS file system.
	    	   
	    	1. The User should refrain from attempting to use
	           the application in a directory that is missing
	           some System files.
	           
	        2. For instance, if the user deletes a "header" file or 
	           a "table" file using the OS file system, 
	           the "catalog" file will not have been properly updated,
	           and the system will output an error to the user
	           if the System attempts to interact with the missing files.

	    	3. However, the User can avoid this calamity via 2 methods.
	    	
	    		a. if the user changes the System path using the command 
	    		   "set path" to an empty directory,
	    	   
	    		b. if the User deletes all the System files,
	    	   	   (while the application is off)
	    	   	   
	    	   	c. the System will generate new System files
	    	   	   as though the system had started from scratch.
	    	   	   
	    	   	d. NOTE: deleting all System files while the
	    	   	   application is running is not suggested.
	    	   	   The application caches a copy of some 
	    	   	   data from the System files, which is
	    	   	   likely to be written to disk with subsequent
	    	   	   System command operations.  Therefore,
	    	   	   in order to ensure a clean re-initialization
	    	   	   of the System, only delete System files
	    	   	   when the application is not running.
					
(m) "run batch [ fileName ]"
	
	1. Executes 1 or more SQL commands found within a batch file.
			
	   a. i.e.: "run batch batch_test_1.txt"
		
	2. Useful for running tests or to improve productivity.
		
	3. Batch files should contain SQL commands as shown above.
		
	   a. Type the SQL commands into a text file,
	      one command per line, each command separated by a 
	      carriage return.
			   
	   b. Feel free to add extra carriage returns or spaces,
	      these should be ignored.
	      
	   c. NOTE: make sure that following the final command in
	      the file, you type a carriage return.  Otherwise,
	      the system will ignore the final command.
		
	4. NOTE: please refrain from placing "run batch" commands within
	   a batch file.  This results in "recursive" calls which has not
	   been debugged yet.
	   
(n) "quit"

	1. The application may be halted / stopped / quit using any
	   of the following ( case-insensitive ) commands.
	   
	   a. end
	   
	   b. exit
	   
	   c. logoff
	   
	   d. log off
	   
	   e. logout
	   
	   f. log out
	   
	   g. q
	   
	   h. quit
	   
	   i. stop


5) File Output / System Files


"DataHeader_tableName": 

	meta-data header files, one per table (i.e.: "DataHeader_xyz", "DataHeader_abc")
			   
"tableName": 

	table file (i.e.: "xyz", "abc", "123")
			   
"catalog.bin": 

	meta-data file, one per folder
			   
any batch files: 

	batch commands (i.e.: "batch_test_1.txt")
       
       
5) Console Output

(a) The following example shows the output from 
    a typical run of the application.


=================================

Database Management System (DBMS)

CS525 - Sec 2 - Steve Talbot

Thu Feb 19 13:58:14 2009

=================================

> show path							// (i)
/home/



> set path /home/stalbot/CS525/Temp					// (ii)
/home/stalbot/CS525/Temp/


The buffer had no eligible pages to commit, so the operation was aborted.
The working directory path name was changed.

> create table xyz(x,y,z)						// (iii)

The table xyz was created.

> insert into xyz values(10,20,30)					// (iv)

The record was inserted.						

> insert into xyz values(40,50,60)

The record was inserted.

> insert into xyz values(70,80,90)

The record was inserted.

> insert into xyz values(100,110,120)

The record was inserted.

> print table xyz							// (v)
 x            y        z   
====||===||====
 10         20      30  
 40         50      60  
 70         80      90  
 100     110     120 


> commit								// (vi)

The pages remaining in the buffer were written to file.

> print buffer							// (vi)
 buffer                  #  file / table          block # 
=========||============||========
 0                            empty                   -1      
 1                            empty                   -1      
 2                            empty                   -1      


> print buffer data							// (vii)

NO RESULTS ...


> select x,y from xyz						// (viii)
   x           y   
====||====
 10         20  
 40         50  
 70         80  
 100      110 


> print buffer							// (ix)
 buffer                   #  file / table         block # 
=========||============||========
 0                                xyz                    0       
 1                              empty                 -1      
 2                              empty                 -1      


> print buffer data							// (x)
table: "xyz"
 x            y        z   
====||===||====
 10         20      30  
 40         50      60  
 70         80      90  
 100      110    120 



> print catalog							// (xi)
# of Tables in Catalog: 1

 Table        Size         # of Att.        Attr       Attr       Attr 
======||====||=========||====||====||=====
 xyz             48               3               x          y          z    



> quit								// (xii)


(b) Descriptions of each command above are discussed below.

	"i"	the default path is shown to be "/home/"
	
	"ii"	the default path is changed.  The System will expect 
	        	to look for System files in this directory.
		
	"iii"   	the table "xyz" was created.  A Header file "DataHeader_xyz"
		was created for the table, and the catalog file was updated.
		A table file was not yet created, because no tuples
		have been inserted yet.
	
	"iv"	4 tuples are inserted into the table "xyz".
		A single main memory buffer pool block is now full.
		
	"v"	The table "xyz" is printed to the console.
	
	"vi"	The first block of the main memory buffer pool 
		containing the tuples belonging to the table "xyz"
		have been "flushed" / written to disk.  The table
		file "xyz" is created on disk.
	
	"vii"	The data in the buffer is printed to the console.
		In this case, since we just did a "commit",
		the main memory buffer pool is empty.
	
	"viii"	A "select" operation requesting 2/3 columns from
		table "xyz", where data is read from disk into the
		main memory buffer pool.
		
	"ix"	Meta data of the main memory buffer pool is shown,
		where we can see that the first block is now
		occupied by the tuples for table "xyz" that 
		were put there by the previous "select" operation.
	
	"x"	Buffer data is again printed to the console,
		but this time the buffer is not empty.  The sole
		buffer pool block is displayed, which includes
		the 4 tuples from table "xyz".
		
	"xi"	The contents of the catalog are printed to the console.
		The sole table that we created so far, table "xyz",
		is shown.