![[Configuration window]](images/config_win.jpg)
This document consists of following topics.
SQ-HAL was successfully tested on Windows and Linux operating systems. In order to run this application, you need to have Perl installed in your computer. There are number of Perl modules required by this application. The modules required are
Table 1: List of Perl modules required by SQ-HAL
| Module | Function |
| Parser::RecDescent | Parser module for SQ-HAL |
| DBI | Handles various database functionalities |
|
Tk |
Implements the user interface |
| Data::Manip | Handles various database related activities |
| Lingua::En::Inflect |
You can download the latest perl from the Internet site www.perl.com and all the above modules from www.perl.com. Installation instructions for perl modules can be accessed from the following sites.
You need about 200 KB space for the SQ-HAL source code and at least 2 MB of disk space for the SQ-HAL parser. Also the screen resolution of 800×600 or higher is recommended.
Copy all he perl source code (files with the extension
".pl") to a new directory where the user has the write
permission. The write permission is required as the application needs to
save the parser for future use. Do not delete, rename files or modify any
of the source code unless you know what you are doing. You can run SQ-HAL
by typing "perl sq-hal.pl" in the command prompt.
When you run SQ-HAL for the first time, following configuration window will come up. You need to enter all these information before continuing to the SQ-HAL.
Figure 1: Configuration window
Source - The location and/or the name of
the data source
Type - List of all the available database
drivers installed in you computer. Select the type of the database if you
already know or otherwise chose the option "Don’t Know". SQ-AL
will attempt to find the database type if you do not know the database type.
If type of database is not in he list (i.e. "Other"), then the SQ-HAL cannot proceed any further until you install the appropriate database driver. For more information about database drivers, referrer to the section 1 (software requirements).
Available sources - These are the
available data sources for the selected database type. You can either
select the data source from this list or type it in the source
entry field.
User - user name to access the database.
Password - password to access the
database.
No of rows - Maximum number of rows to
display when the SQL statement is executed. It is strongly recommended to
keep this value below 100 as this may consume lots of computer resources.
(default - 20)
Enable learning - Enables or disables the
learning functionality of SQ-HAL. (Default - Enabled)
OK - Accept all the configuration values
entered and close this window. These information (except the password)
will be saved to the configuration file ‘sq-hal.ini’ for future use.
If this configuration file is not found (e.g. got deleted), then SQ-HAL will
bring up this configuration window to recreate it.
Cancel - Do no accept changes and close
this window. As it is very important for SQ-HAL to know the database
information, pressing this button will exit the application.
Since SQ-HAL does not store your password to access the database, you need to enter the database password every time you run the program. Therefore SQ-HAL will always bring up the following login window at the start-up.
Figure 2: Database login window
![[Database login window]](images/login_win.jpg)
user - User name to access the database
password - password to access the
database
OK - Accept the user name and password
and continue running SQ-HAL.
Cancel - do not accept the user name and
the password and close this window. This will exit the program.
Once you press OK, then a splash screen will be displayed. During this time, the program will establish a connection to the database and will create or load the SQ-HAL parser. Any errors in database connection or loading the parser will be displayed and the program will be aborted.
Once the SQ-HAL establish successful connection to the database and loaded the parser, it will bring up the SQ-HAL main window.
This is an easy to use, simple window. Following sections describe the features of the main window.
Figure 3: SQ-HAL main window
![[SQ-HAL main window]](images/main_win.jpg)
Natural Language query - Type you natural language queries or questions here.
Translate the query to SQL - As the name
suggests, this button calls the SQ-HAL parser to translate your natural language
query to SQL. The results of the translation is displayed the text area
immediately below this button.
Clear - clear the content in the natural
language query area.
Create your own SQL - This brings up the
window where you can easily create SQL statements by selecting tables and
columns. (Refer to section 8 - Creating your own SQL)
SQL Statement - Translation of natural
language queries is displayed here. If the translation is successful, the
SQL statement is displayed in blue colour or otherwise error messages is
displayed in red colour.
As soon as valid statement is displayed in here, SQ-HAL automatically executes this SQL statement and displays the data in the results table. Also if your previous English queries were unsuccessful, then a learn grammar window will also pop up (Refer to section 9 - SQ-HAL learning functionality)
You can also change the SQL statement or type your own SQL statements here and press ‘Execute SQL’ button to execute and display the results.
Execute SQL - Execute the SQL statement
and display the results in the results table. If here is an error in the
SQL statement, an error message is displayed.
Note that you can only execute SELECT queries. Trying to execute any other type of SQL statement will generate and error message.
Results table - results of the execution of SQL statement is displayed here. You can limit number of rows in the table through the configuration window. (Refer to section 4 - Running SQ-HAL for the first time)
Database - brings up he window that displays the database structure. (Refer to section 7 - Database structure)
Configure - brings up the configuration
window where you can change database and other information. (Refer to section 4
- Running SQ-HAL for the first time)
Exit - Exit from SQ-HAL to the
system. On exit, SQ-HAL may save the parser if it has been newly created
or has been changed during the current session. The parser is save to a
file call "sq_hal_<database_type>_<data_source>_<user_name>.pm".
Saving of the parser may take some time. So please be patient if this is
the case.
The database structure of the current database can be viewed in the database structure window. Various database related information can also be entered in here.
Figure 4: Database structure window
Tables - This left most list contains all
the available table names in the database. When you select a table name
from the list, corresponding column names in the selected table will appear in
the column names list.
Columns - List of column names for the selected table
Related word - select either a table name or column name before pressing this button. This will bring up the following dialog box.
Figure 5: Related words entry dialog box
You need to enter any related words for the selected table name or column name and press OK to accept these words. These words need to be comma separated without any spaces in between them. These new words will then be appended to the SQ-HAL parser.
Close - Close this window and bring back
the SQ-HAL main window to the front.
Table Relationships - This brings up the
following window where you define relationships between various tables in the
database.
Figure 6: Table relationships window
![[Table relationships window]](images/table_r_win.jpg)
Table names list - This left most list
contains the list of all the table names in the database. Select the two
table names, which involves in the relationship by clicking on them. When
you chose the two table names, the two column names list to the right will be
updated with corresponding column names.
Column names list 1 - Column names list
for the first selected table. Select the column name involves in the table
relationship.
Column names list 2 - Column names list
for the second selected table. Select the column name involves in the
table relationship.
Current relationship - This is the table
relationship you have just crated by selecting two table names and corresponding
column names.
Add - Adds he current relationship to the
list of all the relationships. If the relationship already exists,
confirmation is asked to overwrite the existing relationship.
All the relationships - List of all the
relationships for the database, which were created during the current session or
previous sessions. You can change any of these relationships by recreating
that relationship.
Accept all - Accept any changes you have
made to the relationships list (including new relationships and changes to
existing relationships) and close this window. These relationships are
saved to a file for future use.
Cancel - Cancel all the changes made to
the relationships list and close this window.
You can create your own SQL statement with the help of the following window wizard.
Figure 7: Creating SQL using the window wizard
![[Creating SQL using the window wizard]](images/create_sql_win.jpg)
Table names list - List of al the
available table names in the database. Select one or more tables from the
list, which you want to appear in the SQL statement. This selection will
automatically update the column names list and the conditions entry table.
Column names list - List of all the
column names fro the selected table(s). You may select any number of
column names. If you want all the column names (from every selected table)
to appear in the SQL statement, then select the list option ‘All columns’
from this list.
Conditions entry table - This table
contains condition entry fields for all the column names for the selected
table(s). You can ener any number of conditions and each of these
expressions will be joined by the AND operator in the SQL statement.
Condition entry must contain an operator followed by the value (e.g. > 10, =
"ABC"). Note that the string values must be included within the
quotation marks.
SQL statement created - This text field
contains the dynamic SQL statement you created by selecting table and column
names and entering conditions in the conditions entry table. This SQL
statement automatically includes any table relationships if there are table
relationships between the selected tables. You can change this SQL
statement to suit your needs or type your own if you wish.
OK - Accept the SLQ statement and execute
it. The results is displayed in the results table of the of the SQ-HAL
main window. Once the results are displayed, this window gets closed
and the main window is brought to the front.
Cancel - Ignore the SQL statement created
and close this window.
When the learning grammar is enabled, the following window will popup every time some new grammar is to be learned.
Figure 8: SQ-HAL learn grammar window
![[SQ-HAL learn grammar window]](images/learning_win.jpg)
Queries did not understand by SQ-HAL -
This table contains all the previous queries that the SQ-HAL did not
understand. You need to manually select (by clicking on the query) which
of these queries has the same meaning as the query which the SQ-HAL understood.
Queries understood by SQ-HAL - This is
the last query understood by SQ-HAL. The program assumes that your
previous attempts were of this query.
Learn - Learn the selected grammar and
close this window. This process may take a while as the program needs to
analyse each query to find any patters. Learning process changes the
SQ-HAL parser. Therefore when SQ-HAL exits current session, it needs to
save the parser.
Cancel - Do not learn any grammar and
close this window. Both the Learn and this button clear the list of
pending queries, which the SQ-HAL did not understand.
You can enable or disable his learning process in the configuration window. (Refer to section 4 - Running SQ-HAL for the first time.)