mSQL 2.0 User Guide

Mini SQL 2.0

User Guide

Lite's Standard Module 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 the standard output of the Lite script (or as text to be included in the generated HTML of a W3-mSQL page). 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 in a manner similar to the echo function (i.e. sent to the standard output or included in the generated HTML). The semantics of the function are the same as those of printf() in C. The printf() format can include field width and justification information. Specification 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.

It should be noted that unlike 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).

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 arguments 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 argument 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 argument, 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 the path argument is a shell command. The command is executed and the output of the new process is available to be read from the returned file descriptor
>\|	The contents of the path argument is a shell command. The command is executed and any data written to the returned file descriptor is passed as input to the new process

An error is indicated by a returned value of -1. In such a case, the system variable $ERRMSG will contain the error message.

It should be noted that both the named pipe related modes create the pipe prior to accessing it. If the pipe exists in the file system prior to the call, open() will fail.

Example :

$fd = open("/tmp/output", ">");

if ($fd < 0) {

echo("Error : $ERRMSG\n");

} else {

fprintf($fd,"This is a test\n");

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).

Please note that 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 occurred.

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. Only the data read prior to the token is returned, the token character itself is not.

Please note that the token is a single character value. If more than one character is passed in the token argument, only the first character is used.

Example :

$fd = open("/etc/passwd", "<");

$username = readtok($fd, ":");

printf("Username is '$username'\n");

close($fd);

String Manipulation Routines split ( ) split ( str , token )

char * str , * 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 , end

strseg() returns a segment of the string passed as the str argument. 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 , * expr1 , * expr2

tr() performs text translations on the string argument 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 , * expr1 , * expr2

sub() performs string substitutions on the string argument 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 content 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 , * regexp , * 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. A table outlining the available tests is shown below.

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. If the file does not exist or another error occurs, a negative value is returned and the $ERRMSG variable is set to an appropriate error message

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.

It should be noted that 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");

}

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 (having 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.

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.

getppid ( )

getppid ( ) getppid() returns the process ID of the process that is the parent of the process running Lite.

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() converts 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 , min , hour , day , month , 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);

unixtime2* ( ) 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. A list of the functionality provided by the individual routines is shown below.

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

Option	Description
%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");

Password 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.

Element	Contents
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");