QATDB – Query-Able Text Database engine

Risingcognition.com 2009
What is QAT Database?
QAT is an abbreviation for Query-Able Text.
QAT is a storage system which parses structured plain text files in order to
make them query-able.
It’s basically a database engine targeted to small applications with stand-alone
data storage needs.
QAT uses simplified query language and perform all the basic tasks within the
table<>column philosophy.
QAT databases can be easily transported and accessed but the plain text is
encrypted to offer extra security to the application data.
QAT does not need runtimes, as long as .NET Framework 3.5 is installed in the
system.

QAT is simple, QAT is free! Why not power your application’s data with it?

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
QAT internal process

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
QAT .NET methods and properties
Methods
Attach (database file path)
Attaches a QAT database file to the QAT instance.
Returns: True if successful, False if not.

Detach ()
Releases the QAT instance from its data bindings.
Returns: True if successful, False if not.

Authenticate (username,password)
Authenticates the caller onto the currently attached database.
Returns: True if successful, False if not.

CreateDatabase (dbname,username,password,dbfilepath)
Creates, attaches and a authenticates a database in the specified path
Returns: True if successful, False if not.

AddTable (tablename,columns()) + 1 overload

Adds a table or a table with columns to the currently attached database.
Returns: True if successful, False if not.

AddColumn (tablename,columnname/columns()) + 1 overload

Adds a column or multiple columns to a currently attached database’s table.
Returns: True if successful, False if not.

AddUser (username,password,accesslevel)
Adds a user to the currently attached database.
Remarks: See User access levels
Returns: True if successful, False if not.

RemoveTable (tablename)
Adds a column to a currently attached database’s table.
Returns: True if successful, False if not.

RemoveColumn (tablename,columnname)
Adds a column to a currently attached database’s table.
Returns: True if successful, False if not.

RemoveUser (username)
Adds a column to a currently attached database’s table.
Returns: True if successful, False if not.

TableExists (tablename)
Checks if the specified table exists in the database.
Returns: True if successful, False if not.
QATDB – Query-Able Text Database engine
Risingcognition.com 2009
ColumnExists (tablename,columnname)
Checks if the specified column exists in the database, within a table.
Returns: True if successful, False if not.

CountTables ()
Counts the number of tables in the database.
Returns: Count result.

CountColumns (tablename)
Counts the number of columns in the database, within a table.
Returns: Count result.

CountUsers ()
Counts the number of users in the database.
Returns: Count result.

GetTables ()
Gets a list of all tables in the database.
Returns: List of tablenames.

GetColumns (tablename)
Gets a list of all columns in the database, within a table.
Returns: List of column names.

GetUsers ()
Gets a list of all users in the database.
Returns: List of all user’s name and password.

GetTableAID (tablename)
Gets the table current Auto-ID.
Returns: Table current Auto-ID number.

ResetTableAID (tablename)
Resets the table Auto-ID, setting it to zero.
Returns: Table current Auto-ID number.

ExecuteQuery (query,returntype,firstonly)
Executes the specified query on the attached database.
Remarks: Return type is optional. Default is DataTable
Firstonly determines if only the first column from the first row is returned.
Firstonly is optional and has a default value of False.
Returns with Firstonly set to True can and should be treated as Strings
Returns: See Data Return.

TestDBConnection (databasefilepath)
Attempt a file open process to check file availability.
Returns: True if successful, False if not.

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
SynchronizeInstance ()
Force cache synchronization with file.
Returns: Does not return.

InstantSave ()
Force cache to be immediately written to database file.
Returns: Does not return.

AddParameter (parameter) + 2 overloads

Adds parameters to be used in the next query.
Remarks: See QATParameters
Returns: Does not return.

ExecuteScript (script,detachatfinal)
Executes a given QAT Script file.
Remarks: detachatfinal determines if the database should be detached after a
script execution. Commonly used to run scripts that does not require
authentication.
Returns: True if successful, False if not.

Properties
AttachedAndAuthenticated
Checks if there is any database attached and authenticated.
Returns: True or false.

DataBaseName
Get or set database name.
Returns: Database name.

DebugMode
Get or set QAT debug mode. Debug mode will output errors.
Returns: True or false.

FireErrors (Deprecated in 0.415. Invalid from 0.42)

Causes or prevents QAT from firing errors when in debug mode.
Returns: True or false.

LastErrorMessage (Deprecated in 0.415. Invalid from 0.42)

Gets the last message from the errorcatcher.
Returns: Message.

LastQuerySuccessful (Deprecated in 0.415. Invalid from 0.42)

Checks if the last executed query was successful or not.
Returns: True or false.
QATDB – Query-Able Text Database engine
Risingcognition.com 2009
Version
Gets the current QAT CORE version.
Returns: Version.

QATLANG (query language)

Operands (OP)
= Equal
=> or >= More or equal
=< or <= Less or equal
> More
< Less
& Contains
&( Starts with
&) Ends with

Commands

The LIST command

LIST command will query data for viewing purposes.

LIST column,column FROM table

LIST column,column FROM table WHERE col-OP-val,col-OP-val

Ex:
LIST name,age FROM users WHERE age>=20
LIST name FROM users WHERE age>5,name&mar

The CHANGE command

CHANGE command edits the existing data

CHANGE column=value,column=value FROM table

CHANGE column=value,column=value FROM table WHERE col-OP-val,…

Ex:
CHANGE age=22,gender=F FROM users WHERE name&(mar

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
The ADD command
ADD command adds new records to tables

ADD table column=value,column=value

Remark: #? In a column value, returns the table Auto-ID (AID)

Remark: You need to set every single column value

Ex:
ADD users id=#?, name=Mary, age=20, gender=F

The DELETE command

DELETE command deletes records from tables

DELETE table
DELETE table WHERE col-OP-val,col-OP-val

Ex:
DELETE users WHERE age=22

The COUNT command

COUNT command counts the number of occurrences, within the criteria.

COUNT table
COUNT table WHERE col-OP-val,col-OP-val

Ex:
COUNT users
COUNT users WHERE age =>20

The HIGHEST command

HIGHEST command seeks the highest numeric value in a column

HIGHEST column FROM table

Ex:
HIGHEST age FROM users

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
The LOWEST command
LOWEST command seeks the lowest numeric value in a column

LOWEST column FROM table

Ex:
LOWEST age FROM users

The FIRST command

FIRST retrieves a column from the first record in the table

FIRST column FROM table

Ex:
FIRST id FROM users

The LAST command

LAST retrieves a column from the last record in the table

LAST column FROM table

Ex:
LAST id FROM users

The LUCKPICK command

LUCKPICK retrieves the given column from a random row in the table

LUCKPICK column FROM table

Ex:
LUCKPICK tip FROM tips

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
The MATCHLIST command
MATCHLIST will query data for viewing purposes, matching columns within two
tables to replace in the base table.

MATCHLIST column,column FROM table REPLACING

basecolumn=targettable>>targetcolumn>targetbind,...

Ex:
MATCHLIST Name,JobID FROM Users REPLACING JobID=Jobs>>Name>ID

Data return
List(Of String)
To keep QAT easy-to-use, the data returns are as simple as it can get.
After a query to the database, the execute method will return the type List (Of
String) filled with data structured as a table.
List(Of String) is not returned with named columns

Ex:
LIST id,name,age FROM users

Result:
1,Mary,22
2,John,24
3,Walter,34

The columns are comma separated and each item in the list represents a row.

List(Of Array)
Data can also be returned as a list of arrays.
Every list item represents a data row and every array item represents columns.
This return type is internally demodulated and does not need external
demodulation. List(Of Array) is not returned with named columns.

DataTable (default)
Data can also be returned as a datatable.
Datatable is filled with the information, making it accessible to the common
datatable usages such as data source to a combobox or datagrid.
This return type is internally demodulated and does not need external
demodulation. Datatable is returned with named columns.

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
Modulation and Demodulation (deprecated*)
Auto detection of data types needs, in order to function properly, data
modulation.

QAT library includes tools, static methods that will help you in this process.

Every time data is inserted into the database, it needs to get modulated in order
to be flawlessly stored.

Consequently, every time you get a reply from a query, you need to demodulate
data, to translate QAT internal equivalents to characters we can understand,
preventing bad parsing as well.

Modulation, VB.NET example:

Dim Name As String = “Mary Poppins”
Query
“ADD users ID=#?, name=” & QATTOOLS.Modulate(Name)

Demodulation, VB.NET example:

For Each DRow As String In QATReturnList
Dim ParsedCol() As String = Split(DRow,”,”)
MsgBox(QATTOOLS.Demodulate(ParsedCol(2))
Next

Note1: Return types “Datatable” and “List(Of Array)” does not need demodulation.

Note2: QAT data type auto-detection now supports operations with time and dates in
the following format: DD-MM-YYYY HH:MM:SS

*Note3: Version 0.44 fully supports values within apostrophes ( ‘ )

For example:

In 0.43 we should write:

ADD Users ID=#?, Name=John#sSeagull, Addr= Prophets#sStreet#sNº3#s#opR#pc

In 0.44+ we can write:

ADD Users ID=#?, Name=’John Seagull’, Addr=’Prophets Street Nº3 (R)’

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
QAT Parameters
In order to simplify queries and minimize errors, QAT now supports parameters.

You can add a parameter to QAT Core, pointing its identity name and value.

In QATLANG, a parameter identifier comes between “@”. For example,

@myname@ is a valid QAT Parameter.

The AddParameter method:

You can add parameters in 3 different ways:

AddParameter(Parameter As QATParameter)
AddParameter(New QATParameter(“myname”,”Johnny Walker (JR)”)

AddParameter(Parameters As List(Of QATParameter)

Dim ParamLista As New List(Of QATParameter)
Dim QP As New QATParameter(“myname”,” Johnny Walker (JR)”)
AddParameter(ParamLista)

AddParameter(ParameterName As String, ParameterValue As String)

AddParameter(“myname”,” Johnny Walker (JR)”)

Final Query: LIST * FROM Utilizadores WHERE Nome=@myname@

Note1: QATParameter’s identity name does not need “@” symbols when adding.
Note2: QATParameters does not need modulation.
Note3: QATParameters are cleared with every query execution.

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
QAT Script
QAT now supports database task scripting.
QAT Script allows scripted database design and creation or automated
database tasks.

Every instruction must end with the character “ ; ” and must obey to a command
syntax. QAT Script files are plain text but should have *.qatscript extension.

Commands

The CREATEDB command

CREATEDB creates a database with the specified details.

CREATEDB databasename username password databasefilepath;

The ATT command

ATT attaches a database to the current QAT instance.

ATT databasefilepath;

The AUTH command

AUTH authenticates the current QAT instance.

AUTH username password;

The TABLE command

TABLE creates a table.

TABLE tablename;

The COLUMNS command

COLUMNS add columns into a table.

COLUMNS tablename column1,column2,column3…;

The USER command

USER adds users into database.

USER username password accesslevel;

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
The VAR command
VAR creates a variable that can be instantly initialized with a value or left to be
used as a query result carrier.
In order to use variables in queries, they’re name must stand between %%.
For example, if you declare a variable called “myname”, to use it you must type
%%myname%%.
Variables %%time%% and %%date%% are reserved variables.
They represent time and date.

VAR variablename;

VAR variablename ‘value’;

The SET command

SET command changes the value of a variable.

SET variablename value;

The ADDROW command

ADDROW inserts a new row into a table

ADDROW tablename column1=’value’,column2=’value’,…;

The QUERYTO command

QUERYTO executes a query and fill a variable with the result from the first row
and cell.

QUERYTO variablename query;

QAT Script example script

CREATEDB myQATtest admin 123 c:\mytestdb.qat;
TABLE Users;
TABLE Jobs;
TABLE Cars;
COLUMNS Users ID,Name,Age,Job,Car;
COLUMNS Jobs ID,JobName;
COLUMNS Cars ID,CarDesc;
ADDROW Cars ID=#?,CarDesc='Ford Fiesta';
ADDROW Cars ID=#?,CarDesc='Audi A4';
ADDROW Jobs ID=#?,JobName='IT Programmer';
ADDROW Jobs ID=#?,JobName='Hardware Technician';
VAR jid;
VAR cid;
QUERYTO jid LIST JobName FROM Jobs WHERE JobName&'Programmer';
QUERYTO cid LIST CarDesc FROM Cars WHERE CarDesc&'Audi';
ADDROW Users ID=#?,Name='Joe',Age=33,Job=%%jid%%,Car=%%cid%%;

QATDB – Query-Able Text Database engine

Risingcognition.com 2009
User access levels
QAT Database access is conditioned by users and users are divided in 3

access levels.

0 – Database owner. Full access.

1 – Limited. No database design, user operation, change or delete
2 – Limited. View only

The users created with new databases are database owners.

Errorhandling
Internal error reporting has suffered some changes since version 0.415.

The deprecated properties are invalid at the current version.

Everytime QAT Core catches an error, it will be thrown an exception, and this
exception should be caught as QATException.

Along with the exception, an event will be raised too. This event could be used
to maintain activity logs. The event is available through QAT Core.

QATEvent(Message As String, Details As String)

Note: The event it’s not raised with every activity within QAT Core, but this
implementation is scheduled for the next version.

Errorhandle in VB.NET:
Try
QAT.SynchronizeInstance()
Catch ex As QATException
MsgBox(ex.Message & “ – “ & ex.InnerException.Message)
End Try

QATDB – Query-Able Text Database engine

Risingcognition.com 2009