txtSQL Documentation

Welcome to the txtSQL 3.0.0 Beta readme. This page should be able to give you enough of a heads-up to start working with txtSQL. If you still find yourself confused after reading this page, try posting at the forums

1. Extracting txtSQL

When you open the txtSQL package up, you will notice that there are three files; txtSQL.class.php, txtSQL.core.php and txtSQL.parser.php. Extract all three files to the same directory. Create a folder with an arbitrary name; usually by convention, it is named 'data'. This will be the folder containing the databases. It can be located anywhere on the server, but usually it is located in the same folder as where you extracted the two files. Make sure this directory is CHMOD'ed to 0755 or higher.

Now go back to the .zip archive and search for the file 'txtsql.MYI', and extract it to the data directory you just created.

OR

You can just copy the 'data' folder inside the .zip archive to your local harddrive.

2.Configuring the class file

Step one in using txtSQL, is to configure the class file so that it may be included into the php files that may require it. You must define a constant which will tell txtSQL where the rest of the scripts are.

<?php
define('TXTSQL_CORE_PATH', 'PATH/TO/FOLDER/WITH/txtSQL_CORE_FILE');
define('TXTSQL_PARSER_PATH', 'PATH/TO/FOLDER/WITH/txtSQL_PARSER_FILE');
include_once('./txtSQL.class.php');
?>

This way, if the three scripts reside in different folders, txtSQL will successfully be able to locate it with these constants.

2.1 Directory Structure

A valid data directory structure consists of the following format:

+ datafolder ( folder with all the databases in them )
+ database_name
+ table.FRM (column definitions)
+ table.MYD (row data)
+ txtsql
+ txtsql.MYI (included with package)

Basically, a database is a folder inside of the main datafolder.

Also inside the datafolder is the txtsql database, with the txtsql.MYI that comes with the package.

3. Including the class file

Now that we are done configuring txtSQL 3.0.0, we can start working with it. First create a blank php document using your favorite text editor. As I said before, I am currently using TextPad. Save it as 'example.php'.

To make things less complicated, make sure that you save it in the same directory as where the txtSQL scripts are in.

<?php
include('./txtSQL.class.php');
?>

3.1 Instantiating the txtSQL object

In the world of object oriented programming (OOP for short), when classes are instantiated, or a copy of the class is created, a special type of variable called an object is automatically created. The object is a pointer to many more variables or objects that are grouped in a special way. For more information on object oriented programming in php, see http://www.php.net/manual/en/language.oop.php

We need to create an object that points to the txtSQL class and it's variables, so add this to the document

<?php
include('./txtSQL.class.php');
$sql = new txtSQL('./data');
?>

The argument, the text enclosed in the single quotes, is the path to the data directory containing all of the databases.

This folder must contain a folder called 'txtsql' (case-sensative), and inside that folder should be a file called 'txtsql.MYI'. This file contains all of the user/password combinations needed to operate with txtSQL.

This folder & file come packaged with txtSQL. Once the path is correct, you may move on to the next section.

3.2 Connecting to txtSQL

We must now connect to txtSQL, with a correct username and password combination that will allow us to use txtSQL.

The default username for txtSQL is 'root', and the default password for it is blank (It is recomendded that you change the password later on). Now, add the following to the text file

<?php
include('./txtSQL.class.php');
$sql = new txtSQL('./data');
$sql->connect($username, $password); // default is $sql->connect('root', '');
?>

txtSQL officially recognizes you as one of its users, and will allow you to query databases and table.

Refer to the documentation for a list of commands you may use

3.3 Selecting a database

Just like mySQL, before doing anything with a table, you must first tell txtSQL which database the table is located in. This step is not crucial, because you can define a database in most queries alone.

We tell txtSQL what database we are working with by using the following:

4. Executing Commands

In order to make use of txtSQL, you have to call the query function through the $sql object we created earlier.

An example of 'selecting' data:

<?php
include('./txtSQL.class.php');
$sql = new txtSQL('./data');
$sql->connect($username, $password); // default is $sql->connect('root', '');
$sql->selectdb('test'); // database 'test' is now selected
$query = 'SELECT * FROM test.test WHERE id = 10 AND name =~ "John Smith" LIMIT 0, 100';
$results = $sql->query($query);

For more information on the SQL Syntax, see the SQL Syntax section

4.1 Working with the results

The $results variable now contains all of the rows of information inside the table 'test'. Table 'test' was defined as inside database 'test'.

The only rows returned are the ones which fit the credentials that you give it ( The where clause ). You can use a foreach loop in this case to loop through the results

<?php
include('./txtSQL.class.php');
$sql = new txtSQL('./data');
$sql->connect($username, $password); // default is $sql->connect('root', '');
$sql->selectdb('test'); // database 'test' is now selected

$query = 'SELECT * FROM test.test WHERE id = 10 AND name =~ "John Smith" LIMIT 0, 100';
$results = $sql->query($query);
foreach ( $results as $key => $row )
{
print "ID: $row[id], NAME: $row[name]<BR />n";
}
?>

5. Disconnecting from txtSQL

At the end of every script should appear the following line to disconnect from txtSQL. It doesn't stop the script from working if it doesn't appear, it's merely present for development purposes.

<?php
include('./txtSQL.class.php');
$sql = new txtSQL('./data');
$sql->connect($username, $password); // default is $sql->connect('root', '');
$sql->selectdb('test'); // database 'test' is now selected

$query = 'SELECT * FROM test.test WHERE id = 10 AND name =~ "John Smith" LIMIT 0, 100';
$results = $sql->query($query);
foreach ( $results as $key => $row )
{
print "ID: $row[id], NAME: $row[name]<BR />n";
}

$sql->disconnect();
?>

6. Error Handling

txtSQL comes pre-built with error handling capabilities. They are listed below, click a function for example usage and syntax

strict()

get_last_error()

last_error()

errordump()

User Comments - txtSQL 3.0.0 Beta Readme

No comments posted yet;