File	Date	Author	Commit
Example	2009-08-26	panos1962	[b2a350] Update
Sample	2009-08-05	panos1962	[d37984] TEST!
Test	2009-09-04	panos1962	[35b1ba] Utilities library updates
bin	2009-08-04	panos1962@gmail.com	[a3d650] This the first installation
lib	2009-09-14	panos1962	[f9f963] Version 2.4.3 Upload
src	2009-08-26	panos1962	[75abb8] push_server minor bug fixed
src.stable	2009-08-12	panos1962	[14f7bd] Update
tools	2009-08-17	panos1962	[19f6b4] makemake.awk updates
INSTALL	2009-08-17	panos1962	[d562d3] Minor Updates
NEWS	2009-08-26	panos1962	[80b05c] Update
README	2009-08-17	panos1962	[f82bc4] Update
configure	2009-08-12	panos1962	[14f7bd] Update

Read Me

[S]QL [P]owered AWK (SPAWK)
===========================

Source Files
------------
The source file `spawk.c' contains an extension library having to do
with SQL powered awk (name spawk comes from [S]QL [P]owered [AWK]).
Source file `spawk.c' consists of many smaller source files. These
source files lie in `src' and `src.stable' directores and the
`makesrc.sh' shell script is used to construct the `spawk.c' source
file. There is also the `makeprn.sh' shell script for constructing
the `spawk.txt' file which is a convenient source printout.

Stable source files lie rather in `src.stable' rather than `src'
directory. Developers must copy `spawk.c' to `lib/sapwk.c' from
time to time (source code backup).

/*** ARNOLD ***/
----------------
The above comment in the source means that I'm not sure for the code.
A guru of gawk's sources (e.g. Arnold Robins) must check the code in
these code regions.

Various Files' Descriptions
---------------------------
lib/my.cnf	Is a sample system configuration file. This file
		may become /etc/my.cnf to be used as MySQL system
		wide configuration file. The file is been copied
		from MySQL distribution sample configuartion files
		and has been added an example [spawk] group.

lib/home.cnf	Is a private configuration file. This file may become
		some users' ~/.my.cnf file to be used as per user MySQL
		configuration file. There is an example [spawk] group
		adding default database ("payroll") and default field
		separator ("|"). There is also a [payroll] group
		which affects programs name "payroll" (calling
		`spawk_program("payroll")') adding default database
		to "payroll" and defining a different password prompt.
		All thsese additions are examples; you don't have to
		copy in your original MySQL configuration files.

Test/spawk.dd	It's a sample schema to be used for tests. You can load
		this schema with mysql client:

			mysql -A <spawk.dd

lib/spawkrc	It's a sample SPAWK initialization file. Such files
		are `/etc/spawkrc' (system wide) and `~/.spawkrc'
		(per user). Again, these are example files; you don't
		have to copy these files.

lib/vimrc	It's my vimrc. This file is copied to /etc/vimrc via
		`options'. You may not copy or use this file if you
		don't want to.

lib/install	A shell script to install the SPAWK development module.
		Run the following comands after first tar:
			tar xf SPAWK
			sh lib/install

Tools
-----
The following shell scripts are used to construct the final source
and object files. These shell scripts lie in `tools' subdirectory.

makelib.sh	This file is a shell script to link the target shared
		libraries. Usually it is called via make.

makesrc.sh	This file is a shell script to construct the source
		file `spawk.c' from smaller source files lying in `src'
		and `src.stable' directories.

makeprn.sh	This file is a shell script to construct the source
		file printout `spawk.txt' from smaller source files
		lying in `src' and `src.stable' directories. The source
		printout is very convenient for those developers who
		wish to recapitulate the code.

checkawk.sh	This file is a shell script to check the `AWKDIR'
		variable in the Makefile. `AWKDIR' variable must
		be set to the full (or relative) pathname of the
		gawk source directory, e.g.

			AWKDIR = /root/source/gawk

		This directory is only needed for the gawk header
		files which are included in SPAWK sources for
		defining `NODE' types etc.

		There's no MySQL relative variable. We assume that
		MySQL header files lie in `/usr/include' (default
		for gcc), or in `/usr/mysql/include' directory.

MySQL Configuration Variables
-----------------------------
The following variables are being used in SPAWK module:

database	The default database (schema) to connect. Altenatively
		we can use `/etc/spawkrc' or `~/.spakrc' files to
		connect via `USE' commands.

password_prompt	The password prompt to be used when password is needed.
		If not defined, then the default password prompt will
		be prompted.

null		An arbitrary string to be used for null valued column
		representation. This string will be used both in whole
		record returned string as in separate columns returned
		strings. If not defined, then null columns will be
		printed as empty strings.

OFS		An arbitrary string to be used as column separator in
		the whole record returned string. If not defined, then
		the default awk "OFS" output field separator will be
		used as column separator.

CFR		If a "CFR" indexed element is present in `SPAWKINFO',
		then the `spawk_affected' function returns the number
		of the rows involved in updates. If "CFR" is not
		present, then `spawk_affected' returns the number of
		rows actually updated, inserted or deleted.

max_query_len	Is the maximum length of a single query.

max_row_len	Is the maximum length of a returned row.

SSL Support
-----------
The following may be used when using SSL connection protocol.

ssl-key		The name of the SSL key file to use for establishing
		a secure connection.

ssl-ca		The path to a file that contains a list of trusted
		SSL CAs.

ssl-capath	The path to a directory that contains trusted SSL
		CA certificates in PEM format.

ssl-cert	The name of the SSL certificate file to use for
		establishing a secure connection.

ssl-cipher	A colon separated list of allowable ciphers to use
		for SSL encryption.

ssl		If set to zero (0), then connect over a non SSL
		connection. If set to one (1) use SSL. There is no
		need to set this variable. When other SSL variables
		are set, then SSL is used, else SSL is inactive.

skip-ssl	If set (no value needed), then SSL is turned off,
		either if other SSL variables have been set.

Any elemnets already indexed in `SPAWKINFO' array before reading the
configuration files will be left untouched. If there is an element
indexed "no-defaults" in the `SPAWKINFO' array, then no configuration
files will be read at all.

The following configuration files' specific options are not yet
implemented via SPAWK module:

--defaults-extra-file
--defaults-file
--defaults-group-suffix

If there is an element indexed "print-defaults" in the `SPAWKINFO'
array, then the `SPAWKINFO' array will be printed to the standard error
while reading the configuration files; after printing the `SPAWKINFO'
array, the awk process will not stop but continue.

Miscellaneus
------------
In the `bin' directory lies the `spawk' shell script which is an
awk front-end. Instead of calling awk you can call `spawk' with
similar options. Read the code for program's usage.