Mini SQL 2.0

Beta

Lite's Standard Module

Introduction

The standard module is to Lite as the standard C library is to C. It is a library of functions that are available to all Lite programs. It provides basic functionality for string manipulation, file IO and other normal expectations of a programming language.
Outlined below is a description of each of the functions available within the standard module.

Input Output Routines

echo ( )
echo ( string )
char * string
echo() outputs the content of string to be included in the generated HTML. Any variables that are included in string are evaluated and expanded before the output is generated.
$name = "Bambi";
echo("My name is $name\n");
printf ( )
printf ( format [ , arg ... ] )
char * format
printf() produces output that is included in the HTML sent to the browser. It works in the same way as printf() in C. It should be noted that unlink echo(), any variables included in the format string passed to printf() are not expanded before the output is generated. The only way to include variable values in the output is to use C styled format definitions (such as "%s" for a string value etc).
The printf() format can include field width and justification information. Sepcification of a format field as "%17s" will generate a right justified value 17 characters wide. Prefixing the field width definition with the '-' character will produce a left justified result.
Example :
$name = "Bambi";
printf("My name is also %s\n", $name);
fprintf ( )
fprintf ( fd , format [ , arg ... ] )
int fd
char * format
Like printf(), fprintf() produces text output based on the content of the format string and the args passed to the function. Unlike printf(), fprintf() sends the output to a file rather than including it in the HTML sent to the browser. The first arg is a file descriptor as returned by the open() function. See the description of open() below for more information.
Example :
$name = "Bambi";
$fd = open("/tmp/name",">");
fprintf($fd, "My name is $name\n");
close($fd);
open ( )
int fd = open ( path , access )
char * path
char * access

open() opens the object (usually a file) pointed to by path for reading and/or writing as specified by the access arg, and returns a file descriptor for that newly opened file. The possible values for the access flags are:
Flag
  
Description
"<" File is opened for reading
">" File is opened for writing
"<>" File is opened for reading and writing
"<P" Create a named pipe in the file system and open it for reading
">P" Create a named pipe in the file system and open it for writing
"<|" The contents of path is a shell command. Execute the command
and allow reading from the process.
">|" The contents of path is a shell command. Execute the command
and allow writing to the process.
An error is indicated by a returned value of -1. In such a case, the system variable $ERRMSG will contain the error message.
NOTE : both the pipe related modes, i.e. "<P" and ">P", create the pipe prior to accessing it. If the pipe exisits in the file system prior to the call, open() will fail.
Example :
$fd = open("/tmp/output", ">");
if ($fd < 0)
{
	printf("Error : $ERRMSG\n");
}
else
{
	fprintf($fd, "This is a test");
	close($fd);
}

$fd = open("ls -l /etc", "<|");
$line = readln($fd);
printf($line);
close($fd);
close ( )
close ( fd )
int fd

close() closes an open file descriptor. If the descriptor relates to a file or a pipe, the file or pipe is closed. If the descriptor is a process, the stdin of the process is closed (and the process should terminate when it reads an EOF from its input).
NOTE : If you do not close all file descriptors you open then you will eventually run out of file descriptors.
Example :
$fd = open("/tmp/input", "<");
close ($fd);
read ( )
read ( fd , numBytes )
int fd
int numBytes

read() reads numBytes bytes of data from the specified file descriptor and returns the data. It returns the empty string "" when on end of file or error. $ERRMSG will be set if an error occured.
Example :
$fd = open("/etc/passwd","<");
$buf = read($fd, 80);
if ($buf == "")
{
	if ($ERRMSG != "")
	{
		printf("Read Error : $ERRMSG\n");
	}
	else
	{
		printf("Read : End Of File\n");
	}
}
else
{
	printf("$buf\n");
}
close($fd);
readln ( )
readln ( fd )
int fd

readln() reads a line of text from the nominated file descriptor and returns the data. The newline value is not removed from the data returned. Like read(), the return of an empty string indicates EOF or an error. $ERRMSG will be set to a non-empty string on error.
Example :
$fd = open("/etc/passwd","<");
$line = readln($fd);
readtok ( )
readtok ( fd , token )
int fd
char * token
readtok() reads data from the file descriptor until it finds the character specified as the token in the input data. The data read prior to the token is returned, the token is not.
NOTE : The token is a single value character. If more than one character is passed in the token arg, only the first character is used.
Example :
$fd = open("/etc/passwd", "<");
$username = readtok($fd, ":");
printf("Username is '$username'\n");
close($fd);

Flag		Description
"<"		File is opened for reading
">"		File is opened for writing
"<>"		File is opened for reading and writing
"<P"		Create a named pipe in the file system and open it for reading
">P"		Create a named pipe in the file system and open it for writing
"<\|"		The contents of path is a shell command. Execute the command and allow reading from the process.
">\|"		The contents of path is a shell command. Execute the command and allow writing to the process.

String Manipulation Routines

split ( )
split ( str , token )
char * str
char * token
split() splits the contents of a variable into multiple substrings using the value of token as the separator character. The result of splitting the string is returned as an array. If more than one character is passed as the token, all but the first character is ignored.
Example :
$line = "bambi:David Hughes:Hughes Technologies";
$info = split($line,":");
printf("Username = $info[0]\n");
printf("Full name = $info[1]\n");
printf("Organisation = $info[2]\n");
strseg ( )
strseg ( str , start, end )
char * str
int start
int end

strseg() returns a segment of the string passed as the str arg. The segment starts at start characters from the start of the string and ends at end characters from the start of the string. In the example below, $sub will contain the string "is a".
Example :
$string = "This is a test";
$sub = strseg($string, 5, 8,);
chop ( )
char * chop ( str )
char * str
chop() removes the last character from the text string str and returns the new value. The primary use of this function is for chopping end-of-line characters off strings read from files with readln().
Example :
$line = readln($fd);
$line = chop($line);
tr ( )
char * tr ( str , expr1 , expr2 )
char * str
char * expr1
char * expr2
tr() performs text translations on the string arg str based on the contents of expr1 and expr2 and returns the modified string value. expr1 and expr2 are sets of characters. Any character that is found in str that matches a character in expr1 is translated to the corresponding character from expr2. The character sets can be defined by listing individual characters or by providing character ranges ( such as A-Z to indicate all characters between A and Z ). The example below will translate any upper case characters to lower case and translate any exclamation marks '!' found in the string with a full stop '.'
Example :
$str = "Hello There!";
$str = tr($str, "A-Z!", "a-z.");
sub ( )
char * sub ( str , expr1 , expr2 )
char * str
char * expr1
char * expr2
sub() performs string substitutions on the string arg str based on the contents of expr1 and expr2. If the string value passed as expr1 is found anywhere in str it is substituted for the value if expr2. The example below would leave the value "This was a test" in $str. Note that unlike tr() the length of the string can be modified bt sub() as there is no restriction on the contents or length of the value of expr2.
Example :
$str = "This is a test";
$str = sub($str, "is", "was");
substr ( )
char * substr ( str , regexp , pattern )
char * str
char * regexp
char * pattern

substr() extracts substrings from str based on the regular expression regexp and the extraction pattern patter. Any parts of the string that are matched by parts of the regular expression enclosed in parenthesis are made available to the extraction pattern. The first such substring is available as $1, the second as $2 and so on. The string value created by expanding any such variables in pattern is returned. The example below would produce the string "Who's Jack?" as the regular expression enclosed in parenthesis will match a word containing a leading capital letter followed by lower case letter.
Example :
$str = "well, Jack is alright.";
$new = substr($str, ".* ([A-Z][a-z]*) .*", 
	"Who's $1?");

File Manipulation Routines

test ( )
test ( test, filename )
char * test
char * filename
test() offers functionality similar to the test program provided by the shell. Given a filename and a test, it will determine if the file matches the test specification. If it matches, 1 is returned otherwise 0 is returned.
The available tests are

Test File Type
"b" Block mode device
"c" Character mode device
"d" Directory
"p" Named pipe
"s" Non-empty regular file
"f" Regular file
"u" File is setuid
"g" File is setgid

Example :
if (test("b", "/tmp/foo") == 1)
{
	echo("/tmp/foo is a block device\n");
}
unlink ( )
unlink ( path )
char * path
unlink() removes the named file from the file system.
Example :
if (unlink("/tmp/foo") < 0)
{
	echo("ERROR : $ERRMSG\n");
}
umask ( )
umask ( mask )
int mask
umask() sets the umask for the current process (see the system manual page for a description of a umask). As with any numeric value, the mask can be given in decimal, hex or octal.
Example :
umask(0227);
chmod ( )
chmod ( path , mode)
char * path
int mode
chmod() changes the mode of the specified file to the specified mode.
Example :
if (chmod("/tmp/foo", 0700) < 0)
{
	echo("ERROR : $ERRMSG\n");
}
mkdir ( )
mkdir ( path )
char * path
mkdir() creates the directory specified by path.
Example :
if (mkdir("/tmp/myDirectory") < 0)
{
	echo("ERROR : $ERRMSG\n");
}
chdir ( )
chdir ( path )
char * path
chdir() changes directory to the specified path.
Example :
if (chdir("/tmp/myDirectory") < 0)
{
	echo("ERROR : $ERRMSG\n");
}
rmdir ( )
rmdir ( path )
char * path
rmdir() removes the specified director from the file system.
Example :
if (rmdir("/tmp/myDirectory") < 0)
{
	echo("ERROR : $ERRMSG\n");
}
rename ( )
rename ( old , new )
char * old
char * new
rename() renames the specified file from the old name to the new name. You cannot rename files over the boundary of a file system.
Example :
if (rename("/tmp/foo", "/tmp/baa") < 0)
{
	echo("ERROR : $ERRMSG\n");
}
truncate ( )
truncate ( path , length)
char * path
int length
truncate() will set the length of the file to the specified length.
Example :
if (truncate("/tmp/foo", 0) < 0)
{
	echo("ERROR : $ERRMSG\n");
}
link ( )
link ( path , new )
char * path
char * new
link() will create a new link named new to the file specified by path. You cannot create a link over a file system boundary.
Example :
if (link("/tmp/foo", "/tmp/baa") < 0)
{
	echo("ERROR : $ERRMSG\n");
}
symlink ( )
symlink ( path , new)
char * path
char * new
symlink() will create a symbolic link called new to the file specified by path. Note : If the installation process determined that your operating system does not support the symlink() system call this function will not be available.
Example :
if (symlink("/tmp/foo", "/tmp/baa") < 0)
{
	echo("ERROR : $ERRMSG\n");
}
stat ( )
stat ( path )
char * path
stat() provides an interface to the stat() system call. The information from stat() is returned as an array. The elements of the array are:
Field
  
Description
0 Inode number
1 File mode
2 Number of links to file
3 UID
4 GID
5 Size of file
6 atime
7 mtime
8 ctime
9 Block size of file system
10 Number of file system blocks used
Example :
$sbuf = stat("/tmp/foo");
if ( #$sbuf == 0)
{
	echo("ERROR : $ERRMSG\n");
}
else
{
	echo("/tmp/foo is $sbuf[5] bytes long\n");
}

Test	File Type
"b"	Block mode device
"c"	Character mode device
"d"	Directory
"p"	Named pipe
"s"	Non-empty regular file
"f"	Regular file
"u"	File is setuid
"g"	File is setgid

Field		Description
0		Inode number
1		File mode
2		Number of links to file
3		UID
4		GID
5		Size of file
6		atime
7		mtime
8		ctime
9		Block size of file system
10		Number of file system blocks used

Process Oriented Routines

Note : System facilities such as fork and exec are not available in the standard module. As this module is shared by both Lite and W3-mSQL it is not appropriate for such calls to be included here (have web pages fork child processes is not a sound idea). A supplementary module called mod_proc will be made available to provide these facilities.

sleep ( )
sleep ( time )
int time
sleep() will suspend operation of the script for time seconds.
Example :
sleep(5);
system ( )
system ( command )
char * command
system() will execute the command line specified by command in a subshell. Any output generated by the command is included in the HTML output. The exit status of the command is returned to the caller.
Example :
if (system("ls -l") != 0)
{
	echo("Error running ls! \n");
}
getpid ( )
getpid ( )

getpid() returns the process ID of the process running Lite
Example :
$pid = getpid();
getppid ( )
getppid ( )

getppid() returns the process ID of the process that is the parent of the process running Lite.
Example :
$ppid = getppid();
kill ( )
kill ( pid , signal )
int pid
int signal
kill() sends the specified signal to the specified process.
Example :
if (kill(1, 9) < 0)
{
	echo("ERROR : $ERRMSG\n");
}

Date / Time Related Routines

time ( )
time ( )

time() returns the time since 00:00:00 GMT, Jan. 1, 1970, measured in seconds as an integer value.
Example :
$time = time();
echo("The number of seconds since Jan 1 1970 is $time\n");
ctime ( )
ctime ( time )
int time
ctime() converst a value returned by time() into the standard UNIX text representation of the date and time.
Example :
$time = time();
printf("The date and time is '%s'\n", 
	ctime($time));
time2unixtime ( )
time2unixtime ( sec, min, hour, day, month, year )
int sec;
int min;
int hour;
int day;
int month;
int year;

time2unixtime() provides a facility by which you can create a standard UNIX time value (i.e. the time since 00:00:00 GMT, Jan. 1, 1970, measured in seconds) for any specified date/time.
Example :
$time = time();
$time2000 = time2unixtime(0,0,0,1,1,2000);
printf("The number of seconds before the end of the century is %d\n",
	$time2000 - $time);
unixtime2year ( )
unixtime2month ( )
unixtime2day ( )
unixtime2hour ( )
unixtime2min ( )
unixtime2sec ( )
unixtime2* ( time )
int time;
The above functions take a UNIX time value (i.e. seconds since Jan 1, 1970) and return an integer value representing part of the time information.

unixtime2year() - The year in which time falls
unixtime2month() - 1 to 12 representing the month in which time falls.
unixtime2day() - 1 to 31 representing the day in which time falls
unixtime2hour() - 0 to 23 representing the month in which time falls
unixtime2min() - 0 to 59 representing the minute in which time falls
unixtime2sec() - 0 to 59 representing the second from the start of the minute in which time falls

Example :
$time = time();
$year = unixtime2year($time);
$month = unixtime2month($time);
$day = unixtime2day($time);

echo("The date is $day/$month/$year\n");
strftime ( )
time ( fmt, time )
char * fmt; int time;
strftime( ) returns a text representation of the UNIX time value time based on the format string passed as fmt. The available formatting options are

%a day of week, using locale's abbreviated weekday names

%A day of week, using locale's full weekday names

%b month, using locale's abbreviated month names

%B month, using locale's full month names

%d day of month (01-31)

%D date as %m/%d/%y

%e Day of month (1-31 with single digits preceded by a space)

%H hour (00-23)

%I hour (00-12)

%j Day of year (001-366)

%k hour (0-23, blank padded)

%l hour (1-12, blank padded)

%m month number (01-12)

%M minute (00-59)

%p AM or PM

%S seconds (00-59)

%T time as %H:%M:%S

%U week number in year (01-52)

%w day of week (0-6, Sunday being 0)

%y year within the century (00-99)

%Y year including century (e.g. 1999)

Example :
$time = time();
$message = strftime("The time is %H:%M:%S on %A, %e %B", $time);
echo("$message\n");

Passwd file Related Routines

getpwnam ( )
getpwnam ( uname )
char * uname
Returns the passwd file entry for the user specified by uname. The result is returned as an array with the array elements defined as below.

[ 0 ] = username
[ 1 ] = password
[ 2 ] = UID
[ 3 ] = GID
[ 4 ] = GECOS
[ 5 ] = home directory
[ 6 ] = shell

Example :
$pwinfo = getpwnam("bambi");
if ( # $pwinfo == 0)
{
	echo("User 'bambi' does not exist!\n");
	exit(1);
}
printf("Bambi's home directory is %s and his uid is %d\n",
	$pwinfo[5], (int)$pwinfo[2]);
getpwuid ( )

getpwuid ( UID )
int UID
getpwuid() returns the same information as getpwnam() but uses a UID to identify the user rather than a username. See the definition of getpwnam() above for details of the return format and usage.

Network Related Routines

gethostbyname ( )
gethostbyname ( host )
char * host
gethostbyname() returns an array of information about the specified host. Element 0 of the array contains the hostname while element 1 contains the hosts IP address.
Example :
$info = gethostbyname("www.Hughes.com.au");
if ( # $info == 0)
{
	echo("Host unknown!\n");
}
else
{
	echo("IP Address = $info[1]\n");
}
gethostbyaddress ( )
gethostbyaddress ( addr )
char * addr
gethostbyaddr() returns an array of information about the specified host. Element 0 of the array contains the hostname while element 1 contains the hosts IP address.
Example :
$info = gethostbyaddr("127.0.0.1");
if ( # $info == 0)
{
	echo("Host unknown!\n");
}
else
{
	echo("Host name = $info[0]\n");
}

Routines available only in W3-mSQL

urlEncode ( )
urlEncode ( str )
char str
urlEncode() returns a URL encoded version of the specified string. The returned data can then be used in GET method operations without any potential problems of not conforming to the data encoding standard.
Example :
$value = urlEncode("This's a test");
setContentType ( )
setContentType ( str )
char *str
setContentType() can be used to override the default content type sent to in the HTML header of the generated HTML output. If it is to be used, it must be the first line of the script. Note : not even a blank line may preceed a call to setContentType().

Example :
setContentType("image/gif");
includeFile ( )
includeFile ( filename )
char *filename
includeFile() may be used to include the contents of the specified file in the HTML output sent to the browser. The contents of the file are not modified or parsed in any way. If the first character of the file name is a / then the filename is an absolute path name from the root directory of the machine. If it is note, the filename is a relative path from the location of the script file.
Example :
includeFile("standard_footer.html");
Copyright © 1996 Hughes Technologies Pty Ltd.

%a	day of week, using locale's abbreviated weekday names
%A	day of week, using locale's full weekday names
%b	month, using locale's abbreviated month names
%B	month, using locale's full month names
%d	day of month (01-31)
%D	date as %m/%d/%y
%e	Day of month (1-31 with single digits preceded by a space)
%H	hour (00-23)
%I	hour (00-12)
%j	Day of year (001-366)
%k	hour (0-23, blank padded)
%l	hour (1-12, blank padded)
%m	month number (01-12)
%M	minute (00-59)
%p	AM or PM
%S	seconds (00-59)
%T	time as %H:%M:%S
%U	week number in year (01-52)
%w	day of week (0-6, Sunday being 0)
%y	year within the century (00-99)
%Y	year including century (e.g. 1999)

Mini SQL 2.0

Beta

Lite's Standard Module

Introduction

Input Output Routines

echo ( )

printf ( )

fprintf ( )

open ( )

close ( )

read ( )

readln ( )

readtok ( )

String Manipulation Routines

split ( )

strseg ( )

chop ( )

tr ( )

sub ( )

substr ( )

File Manipulation Routines

test ( )

unlink ( )

umask ( )

chmod ( )

mkdir ( )

chdir ( )

rmdir ( )

rename ( )

truncate ( )

link ( )

symlink ( )

stat ( )

Process Oriented Routines

sleep ( )

system ( )

getpid ( )

getppid ( )

kill ( )

Date / Time Related Routines

time ( )

ctime ( )

time2unixtime ( )

unixtime2year ( ) unixtime2month ( ) unixtime2day ( ) unixtime2hour ( ) unixtime2min ( ) unixtime2sec ( )

strftime ( )

Passwd file Related Routines

getpwnam ( )

getpwuid ( )

Network Related Routines

gethostbyname ( )

gethostbyaddress ( )

Routines available only in W3-mSQL

urlEncode ( )

setContentType ( )

includeFile ( )

unixtime2year ( )
unixtime2month ( )
unixtime2day ( )
unixtime2hour ( )
unixtime2min ( )
unixtime2sec ( )