Note
----

This file contains a brief discussion on debugging nested
operators within the rardbms system as of version B0.8. It
is not particularly extensive, and I will expand on this
as time passes. I'd appreciate your comments.

If printing this, watch out for the long lines in the examples...

Debugging nested algebraic expressions
======================================

It can prove quite tricky working out where a nested algebraic 
expression has gone wrong. To make it clearer, I've implemented
a DEBUG facility. 

To activate the DEBUG facility, specify the following parameter on 
the command line, when first starting the system:

DEBUG=Y

For example, to start the program with debugging, type:

LEAP DEBUG=Y

If you want to specify the directory as well, specify the 
DIR parameter, so to start up the system with debugging
and a directory for the data as c:\rardbms, type:

LEAP DEBUG=Y DIR=C:\RARDBMS

Ordering of parameters does not matter.

DEBUG output
============

All of the DEBUG output goes to the report file, which 
contains general information. Most of this general information
appears all of the time, but DEBUG information is preceeded
by "DEBUG:".

For example:

DEBUG: Processing: PROJECT((JOIN((PROJECT((SELECT((EX_BOOK)(PNAME='MIT PRESS')))(ANAME)))(EX_AUTH)(ANAME=EX_AUTH.ANAME)))(SPECIALISM))
DEBUG: Processing: JOIN((PROJECT((SELECT((EX_BOOK)(PNAME='MIT PRESS')))(ANAME)))(EX_AUTH)(ANAME=EX_AUTH.ANAME))
DEBUG: Processing: PROJECT((SELECT((EX_BOOK)(PNAME='MIT PRESS')))(ANAME))
DEBUG: Processing: SELECT((EX_BOOK)(PNAME='MIT PRESS'))
DEBUG: Processing: EX_BOOK
DEBUG: Processed: EX_BOOK
DEBUG: Processed: SELECT((EX_BOOK)(PNAME='MIT PRESS'))
DEBUG: Processed: PROJECT((SELECT((EX_BOOK)(PNAME='MIT PRESS')))(ANAME))
DEBUG: Processing: EX_AUTH
DEBUG: Processed: EX_AUTH
DEBUG: Processed: JOIN((PROJECT((SELECT((EX_BOOK)(PNAME='MIT PRESS')))(ANAME)))(EX_AUTH)(ANAME=EX_AUTH.ANAME))
DEBUG: Processed: PROJECT((JOIN((PROJECT((SELECT((EX_BOOK)(PNAME='MIT PRESS')))(ANAME)))(EX_AUTH)(ANAME=EX_AUTH.ANAME)))(SPECIALISM))

(The date and time has been removed in the interests of space)

It should be clear from the above how the system recurses down through
the expression. When it embarks on an expression, it outputs

"DEBUG: Processing: [expression]"

It recurses into the expression until it reaches a point where it can
resolve an expression, i.e. a relation is found. The relation is then
returned to the earlier process operation, and the following is
output:

"DEBUG: Processed: [expression]"

The program then recurses out of the expression, recursing back in if
necessary (i.e. Where another relation is required).

It should be easy to identify the hierarchy of expressions, and how
the system progresses through a well-formed expression.

DEBUGging
=========

Of course, its necessary to be able to debug the program. The system
makes it clear that it cannot process an expression with plenty of
errors. You'll know if its gone wrong, for example by removing one
or two brackets from the above example, the following output is
produced:

DEBUG: Processing: PROJECT((JOIN((PROJECT(SELECT(EX_BOOK)(PNAME='MIT PRESS'))(ANAME)))(EX_AUTH)(ANAME=EX_AUTH.ANAME))(SPECIALISM))
DEBUG: Processing: JOIN((PROJECT(SELECT(EX_BOOK)(PNAME='MIT PRESS'))(ANAME)))(EX_AUTH)(ANAME=EX_AUTH.ANAME)
DEBUG: Processing: PROJECT(SELECT(EX_BOOK)(PNAME='MIT PRESS'))(ANAME)
DEBUG: Processing: EX_BOOK
DEBUG: Processed: EX_BOOK
[Project] Attempted to add duplicate tuple to hash table! [                                                    ]
[Project] Attempted to add duplicate tuple to hash table! [                                                    ]
[Project] Attempted to add duplicate tuple to hash table! [                                                    ]
[Project] Attempted to add duplicate tuple to hash table! [                                                    ]
DEBUG: Processed: PROJECT(SELECT(EX_BOOK)(PNAME='MIT PRESS'))(ANAME)
DEBUG: Processing: 
*Error: #19: No relation created where required (Brackets may be incorrect).
*Whilst executing: FIND RELATION in 
DEBUG: Processed: 
*Error: #19: No relation created where required (Brackets may be incorrect).
*Whilst executing: JOIN in JOIN(EX_AUTH)(ANAME=EX_AUTH.ANAME)
DEBUG: Processed: JOIN((PROJECT(SELECT(EX_BOOK)(PNAME='MIT PRESS'))(ANAME)))(EX_AUTH)(ANAME=EX_AUTH.ANAME)
*Error: #19: No relation created where required (Brackets may be incorrect).
*Whilst executing: PROJECT in PROJECT
DEBUG: Processed: PROJECT((JOIN((PROJECT(SELECT(EX_BOOK)(PNAME='MIT PRESS'))(ANAME)))(EX_AUTH)(ANAME=EX_AUTH.ANAME))(SPECIALISM))

The asterixed (*) lines appear on the screen... You'll know it when you see it!

The brackets on the third debug operator are wrong: there is no bracket around the entire
statement after the PROJECT statement, and there is no bracket around the select operator
parameters. It should read:

PROJECT((SELECT((EX_BOOK)(PNAME='MIT PRESS')))(ANAME))

The fact that the SELECT operator does not appear directly after the PROJECT operator
gives most of this game away. We can then balance out the brackets on a larger scale, and
have the correct operator:

PROJECT((JOIN((PROJECT((SELECT((EX_BOOK)(PNAME='MIT PRESS')))(ANAME)))(EX_AUTH)(ANAME=EX_AUTH.ANAME)))(SPECIALISM))

