Mini SQL 2.0

Beta

Lite : mSQL's Scripting Language

Introduction

The fact that mSQL can be accessed from virtually every popular scripting language used on UNIX systems has been one of the factors in its popularity. Quite often, however, it is also one of the greatest causes of frustration for users. Adding mSQL support to an existing language, such as Perl or Tcl, requires compilation of a modified version of the language including the mSQL specific code. For an average user this can often be a time-consuming and error prone process.
To help overcome this, mSQL 2.0 includes it's own scripting language, preconfigured with support for the mSQL API. It is also the same language used by W3-mSQL, the WWW to mSQL interface package. People wishing to access mSQL from scripts and via the web now have to learn only one simple yet powerful language.

Basics

Lite has been designed to mimic the syntax and semantics of the C language while reducing some of the complexities and error prone features of C. This is intentional as most programmers working on UNIX machines have a working knowledge of C but look for a more "easy to use" language for scripting. The main changes from C are

All memory management (i.e. allocation and deallocation of memory for variables) is taken care of by the Lite Virtual Machine. Your script does not need to perform any memory management routines.

A variable has no fixed type. It will contain whatever is stored in it (e.g char value, numeric value). When you perform an operation on a variable, such as maths or comparisons, the contents of the variable are checked to ensure they are of the correct type. This concept will become more clear as we progress through this documentation.

There is a dynamic array type. Each element of the array is a variable as described above. The elements are accessed as they are in C, i.e. variable[offset], but they need not be declared before use. That is, the array element is created when a value is stored in it without an pre-definition of the array.

Variables are not pre-declared. They are created when they are first used.

Variable names must start with a $ character. This will be familiar to shell script programmers.

Variables, Types and Expressions

Variables are constructed from a $ sign followed by alpha-numeric characters and the '_' character. The only restriction placed upon the name of a variable is that the first character of a user defined variable must not be an upper case character. There is no need to pre-declare variables as you do in a language such as C. A variable is created the first time you assign a value to it. Similarly, the type of the variable is defined by the value that you assign to it. There are four types of scalar variables

char
integer
unsigned integers
real number

The example code below illustrates the creation of variables

$int_value = 9;
$uint_value = (uint)240983;
$char_value = "Some text value";
$real_value = 12.627;

At any point in time, the type of a value can be changed by using the type cast notation from the C language. If, for example, you wished to include a numeric value from an integer variable in a text string, you would simply cast the integer value to the char type. For example, the code below would result in a char variable that contained the string "1234"

$int_val = 1234;
$char_val = (char) $int_val;

The valid type casts are listed below (note uint casts are valid whereer an int cast would be)

From To Result Example
int char Text representation of numeric string 12 => "12"
int real Real representation of integer value 12 => 12.0
real char Text representation of real value 123.45 => "123.45"
real int Integer representation of real value 123.45 => 123

Array variables are supported by Lite but there is no fixed type for the array. Each element of the array can hold data from any of the available data types. An array is created by assigning a value to one of the array elements such as

$arrayval[3] = "Foo";
$arrayval[4] = 5;
$arrayval[6] = 1.23 + 5.38;

Lite exrepssions are formed from mathematical equations incorporating the values of variables and values returned from function calls. Lite is a little more flexible than other languages such as C. It will allow you to do maths operations on all data types including the char type. Adding two char values together results in the concatenation of the two strings. You can also perform maths on values of different types by casting the value to the correct type within the expression. Example are given below;

$charval = "Hello" + " there!";
$intval = 8 + 1;
$charval = (char)$intval + " green bottles";

The first expression would result in the char value "Hello there!". The second would result in the integer value 9. The final expression would result in the char value "9 green bottles" using the text representation of the value of $intval from the previous line. Maths expression of any complexity, including any number of sub expressions enclosed in ( ) characters, are supported.
The table below lists the available maths operators and the data types to which they may be applied.

Operator Description Int Text Real
+ Addition Yes Yes Yes
- Subtraction Yes No Yes
/ Division Yes No Yes
* Multiplication Yes No Yes

A special operator supported by Lite is the count operator written as the # sign. The count operator is used to determine the size of certain vairables. If you apply the count operator to a char value it will evaluate to the number of characters in the string. If you apply it to an array it will evaluate to the number of elements in that array. In the first example below, $intval would contain the value 5. In the second example, it would contain 3.

$charval = "Hello";
$intval = # $charval;

$array[0] = 0;
$array[1] = 1;
$array[2] = 2;
$intval = # $array;

From	To	Result	Example
int	char	Text representation of numeric string	12 => "12"
int	real	Real representation of integer value	12 => 12.0
real	char	Text representation of real value	123.45 => "123.45"
real	int	Integer representation of real value	123.45 => 123

Operator	Description	Int	Text	Real
+	Addition	Yes	Yes	Yes
-	Subtraction	Yes	No	Yes
/	Division	Yes	No	Yes
*	Multiplication	Yes	No	Yes

Conditions and Loops

Conditions are provided by Lite using the same syntax as C. That is, the conditional block is started by an 'if (condition)'. The blocks of code are defined using the { and } character. Unlike C, you must always wrap code blocks in { } characters (in C you don't have to if the code block is only one line long). After the initial code block, an optional 'else' block may be defined.
Multiple parts of the conditional expression may be linked together using logical ANDs and ORs. Like C, the syntax for an AND is && while the syntax for an OR is ||. As you will see in the example below, Lite provides more flexibility than C in conditions containing text values. You can compare two text values using the '==' equality test or the '!=' inequality test rather than having to use a function such as strcmp().

if ($intval > 5 && $intval < 10)
{

echo("The value is between 5 and 10\n");
}
else
{

echo("The value is not between 5 and 10\n");
}

if ($charval == "")
{

echo("The variable contains no value!!!\n");
}

Lite supports only one form of looping - a 'while' loop. The syntax and operation of the while loop is identical the the while loop offered by the C language. This includes the use of 'continue' and 'break' clauses to control the flow of execution within the loop.

while ($intval < 10)
{

$intval = $intval + 1;
}

while ($charval != "")
{

$charval = readln($fd); if ($charval == "Hello")
{

break;
}
}

User Defined Functions

As with most moderm programming languages, Lite allows you to write functions. In a Lite script a function is defined as follows :-
funct functName ( type arg, type arg ...)
{
	statements
}
As the definition dictates, a function must be started with the funct label. The remainder looks like a C function declaration in that there is a function name followed by a list of typed arguments. Any type may be passed to a function and any type may be returned from a function. All values passed to a function are passed by value not by reference. A few example functions are given below.
funct addition ( int $value1, int $value2 )
{
	$result = $value1 + $value2;
	return ( $value );
}


funct merge ( array $values, int $numVals)
{
	$count = 0;
	$result = "";
	while ( $count < $numValues)
	{
		$result = $result + $values [ $count ];
		$count = $count + 1;
	}
	return ( $result );
}


funct sequence ( int $first, int $last )
{
	$count = 0;
	while ( $first < $last )
	{
		$array [$count] = (char) $first;
		$first = $first + 1;
	}
	return ( $array );
}
It must be noted that function declarations can only be made before any of the actual script code of the file. That is, all functions must be defined before the main body of the script is reached.

User Defined Libraries

To help provide an efficient programming environment, Lite (and W3-mSQL) allows you to build a library of functions and load the library into your script at run-time. This allows for effective re-use of code in the same way the languages such as C allow you to re-use code by linking against libraries. The main difference is that the library is not "linked" into the script, it is loaded on request at run-time (a little like a C shared library). If the functions that were defined in the previous section of this manual were placed into a library called "mylib", a script could access those functions by loading the library as depiced below.
load "mylib.lib";

/*
** Now we can use the functions from the library
*/
$array = sequence(1,10);
$count = 0;
while ($count < # $array)
{
	printf("Value %d is '%s'\n", $count, $array);
	$count = $count + 1;
}
The power and convenience of Lite libraries is most obvious when writing large WWW based applications using W3-mSQL. Like any application, there will be actions that you will need to perform several times. Without the aid of libraries, the code to perform those actions would need to be re-coded into each W3-mSQL enhanced web page (because each HTML file is a stand-alone program). By placing all these commonly used functions into a library, each web page can simply load the library and have access to the functions. This also provides a single place at which modifications can be made that are reflected in all web pages that load the library.
Library files are not like normal Lite script files. A Lite script file is a plain ASCII text file that is parsed at run-time by Lite. A library file containes pre-compiled version of the Lite functions that will load faster as they do not need to be re-parsed every time they are used. A Lite library file is created by using the -l flag of the Lite interpreter. If a set of functions was placed in a file called mylib.lite, a compiled version of the library would be created using the syntax shown below.
lite -lmylib.lib mylib.lite
The -l flag tells Lite to compile the functions and write the binary version of the functions to a file called mylib.lib. This is similar to the concept of using the C compiler to create an object file by using the -c flag of the compiler.
There are three points that should be noted about the use of Lite libraries. Firstly, it should be noted that a Lite library can only contain functions (i.e. it cannot contain any "main body" code that you would normally include in a script file). Secondly, like functions themselves, a library can only be loaded into a Lite script prior to the start of the main body code. Finally, the path given to the load command within the script does not enforce a known location for the library file. If you specify the library file as "mylib.lib" the Lite will expect the library file to exist in the current directory. You can of course provide a complete pathname rather than just a filename to the load command.

Copyright © 1996 Hughes Technologies Pty Ltd.